软著交付流水线 shay-Ckm/dsh-skill-softcopyright

dsh-skill-softcopyright

软件著作权交付流水线的 DSH 插件：内置 4 个交付技能 + 10 步编排 + 确定性校验工具。

当前状态：M1 完成（技能层 + 运行时 + 体检工具）。
工具层（sc_manual / sc_aigc / sc_source / sc_atlas / sc_proof）在 M2，编排层（sc_audit / sc_pipeline / /sc- 命令）在 M3。
设计文档：docs/软著交付流水线插件-开发设计文档-v0.1.md（v0.2）。

内置的 4 个技能

| 技能 | 角色 | 内容 |
| python-software-delivery | 编排方（Phase 1–5.6） | 5 篇 references + 12 个脚本 |
| manual-ui-screenshots | 下游，Phase 5.2 界面图集 + 回填 docx | 1 篇 reference + 8 脚本 + 4 前端资产 |
| aigc-review-reduction | 下游，Phase 5.4 降 AIGC 率 | 3 篇 references + 2 脚本 |
| software-copyright-aigc-appeal | 下游，Phase 5.5 申诉证明 | 4 脚本 |

技能正文原样收录，磁盘上的 SKILL.md 与原始技能包 byte-identical（harness 用 SHA-256 锁住）。
插件只在其上追加一段"工具与流水线指引"，该注入可用 skills.injectToolGuide: false 关闭。

已做的去重：
- check_aigc.py 两个版本统一为 17907 字节的超集版（含 --struct 21 类结构扫描）。
- references/aigc-reduction.md 经核对本来两份就一致，保留双份但由 harness 锁一致性。

提供的工具

混合粒度（设计文档 §3.3）：高频/需强 schema 的单列，同领域的收进一个 action 分组工具，以控制常驻每次请求的 schema token。

| 工具 | 粒度 | action | 关键点 |
| sc_doctor | 细粒度 | — | 体检：两条 Python 链、Word COM、受管 seam、资产完整性 |
| sc_manual | 分组 | check stats check-figs insert-atlas extract render-pdf | stats 默认走渲染链取 Word COM 真实页数；返回 pagesSource |
| sc_source | 分组 | gen-doc check-doc build-package smoke collect-hashes stats-hashes | 产出四处口径的权威 N 文件/M 行；build-package 会替脚本判 sdist 失败 |
| sc_aigc | 分组 | scan struct probe | 退出码恒 0 无语义，需比对 vocabReductionTarget / structuralResidueTarget |
| sc_proof | 分组 | gen-docx gen-html page-estimate check-inline-js | 法律事实留占位符；检测"保存失败但退出码 0" |
| sc_atlas | 分组 | validate check-html scale shoot | shoot 走渲染链（Playwright + 真实 Chrome），耗时长 |
| sc_audit | 细粒度 | four-way source-scope figures | 四处口径一致性审计（原技能包完全没有的能力） |
| sc_pipeline | 细粒度 | status plan advance checkpoint skip recompute-facts reset | 10 步状态机 + Checkpoint 门禁 |

交付流水线（M3）

assets/pipeline.yaml 是一份可定制的 10 步清单：改阶段、改判据、改顺序、加不变量都只改 YAML，不动 JS。启动时 lib/pipeline/manifest.js 严格校验（id 唯一、技能名、requires 环、判据 kind），写错立刻报错。

| 阶段 | 标题 | 完成判据 |
| p1-requirements | 需求确认 | 用户确认（4 项决策） |
| p2-development | 开发 | 用户确认 |
| p3-regression | 回归测试 | 用户确认 |
| p4-package | 源码打包 | dist/.zip + sc_source build-package 证据 |
| p5-1-manual | 使用说明书 docx | 说明书 docx + sc_manual check + 图位≥30 + 页数须真实渲染 |
| p5-2-atlas | 界面图集 + 回填 | sc_manual check-figs：图题数 == 图片数、残留占位段 0 |
| p5-3-srcdoc | 源代码文档 docx | 源代码文档 docx + sc_source check-doc |
| p5-4-aigc | 降 AIGC（按需） | 降幅 ≥50% + 结构性残留 0 |
| p5-5-proof | 申诉证明（按需） | 两份 docx + collect-hashes + 四处口径一致 |
| p5-6-delivery | 统一交付 | 四处口径一致 + 用户确认 |

门禁怎么工作（「中约束」）

推进必须调用 sc_pipeline action=advance，它要求三类判据全过 且 confirmedByUser === true：

| 判据 | 含义 |
| artifacts | 产物 glob 必须存在 |
| evidence | 某个 tool+action 必须已通过，且晚于本阶段开始时间（防"改了内容没重跑校验就推进"） |
| measure | 字段相等/上下界、页数来源必须是真实渲染、四处口径一致 |

mustStopAfter: true 本身即要求用户确认 —— 这是 harness 抓出来的设计缺口：最初只有显式写了 user-confirmed 判据的阶段才拦确认，于是 p5-1 / p5-2 可以不带确认就推进，恰好违背技能正文的铁律。

为什么不做成 agent/pre-step 硬拦截：那属于深度干预 agent 循环，调试与误伤成本都高，且会和 Aegis / browser-skill 抢同一个接缝。"绕过去会被 sc_audit 抓出来"比"绕不过去"更稳。

状态与证据

- 状态文件：项目内 /.dsh/softcopyright/state.json（项目自包含、多项目隔离）
- sharedFacts 是「四处口径」的单一真源：「N 个源文件 / M 行」只存这一份，四处消费点都读它 → 任何一步收窄范围，recompute-facts 重算一次就自动对齐
- 每次工具执行自动记为证据（pipeline.recordEvidence，可关）

斜杠命令

/sc-status 查进度 · /sc-audit 立刻跑四处审计 · /sc-milestone 标记已汇报 · /sc-reset confirm 清空状态

⚠️ 行数口径必须与上游脚本一致（已交叉验证）

sc_audit 的价值全在于它报的「M 行代码」与源代码文档封面、哈希清单、研发日志一致。
若我的行数口径与生成那些文档的脚本不同，审计就会误报不一致 —— 比没有审计更糟。

上游口径是 Python 的 f.read().splitlines() / fh.readlines()：结尾换行符不产生额外一行（"a\nb\nc\n" 是 3 行而非 4 行）。我第一版写成 split(/\r?\n/).length，会多算 1 行。

现已用真实脚本交叉验证（linecount-parity.mjs）：

脚本报告 : files=12 lines=1865 bytes=79467 我的口径 : lines=1865 逐文件不一致数 : 0 结论：PASS —— 行数口径与上游脚本完全一致

文件筛选规则（source.includeExt / excludeDirs）是可配置的，与行数口径无关；上面 12 vs 11 的文件差异就来自 includeExt 默认只收 .py。

三个必须知道的语义（来自对 20 个脚本的逐字精读）

1. 退出码语义分三类，不能一律当"成功/失败"：
- check_manual_docx / manual_stats / check_src_doc / check_manual_with_figs /
validate_atlas / validate_html / probe_residue / check_inline_js /
package_smoke_template → 退出码就是校验结论。
- check_aigc / build_src_package / gen_proof_docx / gen_src_docx /
page_estimate / 两个哈希脚本 / insert_atlas_into_manual / scale_units → 恒退出 0，退出 0 也可能业务失败。插件已替它们判：
sdistStatus、generated[]、existingImages（二次插图）等字段就是判据。
- argparse 脚本 → 退出码 2 是"用法错误"，插件报 ran=false 而不是"不通过"。

2. 两个哈希脚本的汇总统计打在 stderr，键名还不同（# TOTAL_FILES=… vs # FILES=…）。插件同时捕获两个流。

3. check_aigc 没有任何达标语义。降 AIGC 是否达标必须按配置阈值判断，插件只提供数字并附上阈值提示。

路径守卫（替代沙箱策略）

工具层通过 ctx.subprocess 直接 spawn「解释器 + 包内只读脚本」。该 seam 不带沙箱策略与审批，而带策略的 ctx.shell 只接受 shell 命令行字符串 —— 我们的路径含中文与空格，拼命令行会引入一个随时会炸的转义层。因此边界改在参数层：用户提供的每个文件路径都必须落在会话工作区、配置的 allowlist、或插件自身只读资源目录之内，越界即拒绝并给出可操作提示（lib/guard.js）。可用 security.pathGuard.enabled: false 关闭（不建议）。

两条 Python 链（实测结论）

本插件区分两条解释器链，按 action 选择而不是统一用一个：

| 链 | 解释器 | 能力 | 用它做什么 |
| generate | 随包 Python（DSH 自带 3.12.14） | python-docx 1.2.0、lxml、Pillow；无 pywin32、无 playwright | 生成与校验 docx、打包、哈希统计 |
| render | C:\Python314\python.exe | pywin32 312 + Word 16.0、python-docx 1.2.0、playwright 1.62.0 + chromium-1234 | Word COM 取真实页数、docx→PDF、真实界面截图 |

页数与 PDF 以 Word COM 为权威口径（决策 Q9）。sc_manual action=stats 会始终返回 pagesSource 字段，让"这次页数是估的"不可能被忽略。

界面图集的真实运行截图走 render 链 —— 该链已装 playwright 1.62.0 与 chromium，本机另有真 Chrome / Edge 可用 channel 启动（技能正文警告过：用 Playwright 自带 chromium 或无头 GPU 会整屏全黑）。因此不需要 bsk，也不需要新装依赖。

安装

本插件是一个 DSH profile bundle（package.json 声明 dsh.bundle.patch，并通过 exports["./cordis.patch.yml"] 暴露 patch）。

1. 放置包体

$src = "E:\Users\L\Desktop\个人ai项目\deepseel-harness\plugins\dsh-skill-softcopyright" $dst = "C:\Users\L\.dsh\profiles\desktop\node_modules\dsh-skill-softcopyright"
if (Test-Path $dst) { Remove-Item $dst -Recurse -Force }
New-Item -ItemType Directory -Force -Path $dst | Out-Null
foreach ($i in @("package.json","cordis.patch.yml","lib","assets","README.zh.md")) {
Copy-Item -LiteralPath (Join-Path $src $i) -Destination $dst -Recurse -Force
}

⚠️ 不要复制开发用的 node_modules/。 该目录下是为本地 harness 从 app.asar 抽出的官方包副本；一旦它随包进入 profile，Node 会优先从插件自己的 node_modules 解析 @deepseek-ai/cordis，形成第二份 cordis 实例，破坏 Service 单例约束。
同理，本插件刻意不写进 profile 的 dependencies：pnpm 对本地目录依赖会建软链，软链会让 Node 以真实路径（工作区）解析，从而暴露上述副本。这是有意为之的取舍，不是遗漏。

2. 声明为 bundle

在 C:\Users\L\.dsh\profiles\desktop\package.json 的 dsh.profile.bundles 末尾追加：

"dsh-skill-softcopyright"

（bundle 自己提供的 Loader 行 id 是 skill-softcopyright。你可以像 browserskill 那样，再在 cordis.patch.yml 里用同一个 id 覆盖它的 config —— 层次语义是后写者胜，不会产生重复行。）

3. 重启

配置改动（cordis.patch.yml / package.json）热生效，但插件 JS 模块代码不会（ESM 模块缓存）。改了 lib/ 下任何文件都必须重启 DSH 桌面进程。

4. 在哪里能看到它

| 页面 | 数据来源 | 本插件 |
| 设置 → 内置插件（只读清单） | pluginInventory/list = 每条非 group 的 Loader 行 | ✅ 显示为 dsh-skill-softcopyright，阶段 active |
| 侧边栏 → Plugins（可管理） | profile 的 bundles 及可寻址行 | ✅ 声明为 bundle 后出现 |

5. 验证

- 新会话的 skill 目录里出现上述 4 个技能。
- 调用一次 sc_doctor，应报告两条链 状态: OK、seam: subprocess、结论：可用。

配置

写在 profile 的 cordis.patch.yml 里本插件条目的 config 字段（由 loader 依据 Config schema 校验后传给 apply()）。

⚠️ 不是 $DSH_HOME/settings.yaml。 实测 DSH 0.1.7-rc.2 中 @deepseek-ai/dsh-settings 只导出 SettingsConflictError / SettingsForms / redactSecrets， installSettingsSection / settingsNamespace 不存在；settings.yaml 机制也已废弃（本机的 settings.yaml 早已被改名 settings.yaml.imported）。
另外：配置改动热生效，但 lib/ 下的代码改动需要重启进程。

- id: skill-softcopyright
name: dsh-skill-softcopyright
config:
skills:
enabled: true
assetRoot: "" # 空 = 包内 assets/skills/ injectToolGuide: true # 是否在技能正文末尾追加工具/流水线指引
enabledSkills: [] # 空 = 全部 4 个

tools:
doctor: true

runtime:
pythonPath: "" # 空 = 自动解析随包 Python renderPythonPath: "C:\\Python314\\python.exe" # 需 pywin32 + Word 的 Python defaultTimeoutMs: 60000 longTaskTimeoutMs: 300000

自检与测试

两个 harness 都需要一些开发用依赖（node_modules/ 已被 .gitignore 忽略，全新检出后须重建一次）：

| 依赖 | 谁需要 | 来源 |
| yaml | lib/skills.js（解析 frontmatter） | profile 的 node_modules/yaml |
| @deepseek-ai/{schemastery,dsh-tools,dsh-util-values,dsh-brand,cosmokit,cordis,dsh-scope,dsh-llm,dsh-typert-protocol,dsh-util-crypto,dsh-timeout,dsh-sandbox} | lib/index.js / lib/tools/doctor.js 的真实依赖链 | 从 app.asar 用 tools/asar-extract.mjs 抽出 |

$p = "E:\Users\L\Desktop\个人ai项目\deepseel-harness\plugins\dsh-skill-softcopyright" $dst = "$p\node_modules" $ref = "E:\Users\L\Desktop\个人ai项目\deepseel-harness\_ref_skills\_dsh\dsh\node_modules" $node = "E:\Users\L\AppData\Local\Programs\DeepSeek Harness\resources\runtime\primary-runtime\dependencies\node\bin\node.exe" $asar = "E:\Users\L\AppData\Local\Programs\DeepSeek Harness\resources\app.asar"

New-Item -ItemType Directory -Force -Path "$dst\@deepseek-ai" | Out-Null
Copy-Item -Recurse "C:\Users\L\.dsh\profiles\desktop\node_modules\yaml" "$dst\yaml" -Force
其余官方包：按 harness 报出的缺失名逐个抽出（见 tools\asar-extract.mjs 用法）

然后：

$p = "E:\Users\L\Desktop\个人ai项目\deepseel-harness\plugins\dsh-skill-softcopyright"

语法检查
node --check "$p\lib\index.js"

M1 验收 harness（133 项断言，覆盖 A1–A4） $env:DSH_HOME = "C:\Users\L\.dsh"
node "$p\test\harness.mjs"

harness 直接测 lib/skills.js、lib/runtime.js、lib/tools/doctor-core.js 这三个不 import @deepseek-ai/ 的模块（那些包只存在于 app.asar 内，普通 node 进程 import 不到）。因此 lib/index.js 与 lib/tools/doctor.js 只能做语法检查，其运行时验证依赖 profile 重载后的集成测试。

目录结构

lib/
index.js 插件入口：name / inject / apply / Config skills.js L2 技能提供方（ctx.skills.registerProvider） runtime.js L1 两条 Python 链 + 受管子进程 seam + UTF-8 环境 tools/ doctor.js sc_doctor 注册层（唯一 import defineTool 的地方） doctor-core.js sc_doctor 体检逻辑（可在 DSH 外测试） assets/skills/ 4 个技能的 SKILL.md / references / scripts / assets test/harness.mjs M1 验收 harness

设计要点

- 子进程走受管 seam：优先 ctx.subprocess（resolveExecutable / spawn /
handle.collected.stdout.readFrom(0)），而不是裸 node:child_process —— 受管 seam
有界收集输出、托管进程组、可终止，且不依赖受限模式下可能被拒的管道 stdio。
服务缺席时退回 node:child_process 并把 seam: 'node' 显式标注出来，降级可见。
- 超时双保险：超时回调除 abort 外还主动调用 handle.terminate()。
只依赖 provider 响应 abort 信号会让长时间脚本挂死调用方（M1 实测踩到）。
- UTF-8 强制注入：Windows 上 Python 默认用 cp936 写 stdout，中文会乱码；插件固定注入 PYTHONUTF8=1 / PYTHONIOENCODING=utf-8 / PYTHONUNBUFFERED=1。
- 无客户端 half：不声明 dsh.client，不需要前端构建链（决策 Q7）。
- 启动期严格校验：assetRoot 缺失、SKILL.md 无 frontmatter、scripts/ 不存在、 enabledSkills 写了未知名 —— 一律在 apply() 时抛错，快速失败优于静默降级。

路线图

| 里程碑 | 内容 | 状态 |
| M1 | 插件骨架 + 4 技能注册 + 运行时 + sc_doctor | ✅ |
| M2 | sc_manual / sc_aigc / sc_source / sc_atlas / sc_proof | 待做 |
| M3 | pipeline.yaml 清单 + 状态机 + 门禁 + sc_audit + /sc- | 待做 |
| M4 | README、npm 打包、端到端验收 | 待做 |