Skip to content

PR-05 · coding-agent 适配层：矩阵文档与防漂移断言 - #168

Open
titanwings wants to merge 6 commits into
ds/02-parse-zero-credfrom
ds/05-agents
Open

PR-05 · coding-agent 适配层：矩阵文档与防漂移断言#168
titanwings wants to merge 6 commits into
ds/02-parse-zero-credfrom
ds/05-agents

Conversation

@titanwings

@titanwings titanwings commented Sep 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

状态 · 2026-09-15：CI 30–79 红，不作为合并入口。 这条分支的树与它自带的测试对不上——
重建快照不完整（例：ds/01 只有 20 个测试文件，集成分支有 86 个）。它的功能已经包含在集成分支
dot-skill-test 与后续分支里。

保留这条分支的用途是每功能一份证据文档（docs/evidence/pr-NN-*.md）与当时的改动前后对比，
不是待合并的代码。权威状态与已知缺口：docs/v2/STATUS.md。

这是一次等价重建，不是原分支的还原。

  • 基底不是 dot-skill-test，而是 ds/02-parse-zero-cred。 原因：本链每一环的内容都已包含在 dot-skill-test 里，
    若以它为 base，diff 会是空的（原计划文档 dst-evidence/PR-BODIES/PR-PLAN.md 早已预判这一点）。
    链式 base 才能让每个 PR 只显示这一个功能的改动。
  • 提交信息：能从会话转录里恢复的原样保留；恢复不到的原提交（130 条里有 50 条，多为单文件文档提交）
    用 chore(<区>): 重建 …（原提交信息未记录） 标注，不冒充原文。
  • 文件内容是集成分支上的最终态，不是历史中间态。原分支的 per-commit 文件树随 /tmp 清空丢失，
    转录只保留了提交信息与每次 git add 的路径清单。
  • 自检：19 条分支从基线依次应用后，链尾树与 dot-skill-test 逐字节相同（空 diff），
    所以没有任何文件被漏掉或重复归属。
  • 原版 ds/01-node-core、ds/04-prompts（丢失前已推送的幸存原件）未改动，本链的同名环节以 -rebuilt 后缀区分。

本 PR：ds/05-agents → ds/02-parse-zero-cred，5 个提交，752 insertions(+), 16 deletions(-)。

本 PR 的提交清单
  • chore(evidence): 重建 docs/evidence/pr-05-agents.md（原提交信息未记录）
  • chore(v2): 重建 docs/v2/HOSTS.md（原提交信息未记录）
  • chore(check-agent-ids): 重建 scripts/check-agent-ids.mjs（原提交信息未记录）
  • chore(agents.test): 重建 tests/agents.test.mjs（原提交信息未记录）
  • feat(v2): add the coding-agent support matrix as shared host data

PR-05 · coding-agent 适配层：矩阵文档与防漂移断言

  • 分支：ds/05-agents（基于 dot-skill-test）
  • 交付：docs/v2/HOSTS.md、tests/agents.test.mjs、scripts/check-agent-ids.mjs、INSTALL/INSTALL_EN/README 的宿主章节
  • 本文纯文字，无截图；证据目录 dst-evidence/ 未入库（.gitignore 已含）

1. 变更

# 提交 内容
1 test(v2): assert the host matrix and the installer's host table cannot drift tests/agents.test.mjs：解析 bin/distilly.mjs 的 hosts / aliases / --help 三处，与 src/hosts/agents.mjs 逐宿主比对；钉住 8 宿主、双语 note、CLI/clone 路线能力集合、cloneCommand 的项目级行为、命令串里不得回流旧仓库名
2 chore(scripts): add an optional upstream cliId check scripts/check-agent-ids.mjs：本机拿得到上游 CLI 时逐个实测 --agent 目标合法性；拿不到就 skipped: upstream skills CLI unavailable 且 exit 0（不进 CI、不联网安装）
3 docs: point the per-host install sections at docs/v2/HOSTS.md INSTALL.md / INSTALL_EN.md 新增 "v2 入口与宿主适配" 节并给出 bin/distilly.mjs 用法；旧「选择你的平台 / Install Distilly」整节保留但标注 Deprecated；README.md 安装段改为指向 HOSTS.md，旧 clone 说明折叠进 <details> 并标注 deprecated
4 docs(v2): add the bilingual host adaptation matrix docs/v2/HOSTS.md：中文段 → --- → ## English，8 宿主逐行给 id / 显示名 / 全局目录 / 项目级目录 / 能力 / 逐字命令 / 中英注意事项 / 怎么验证；另加"换宿主要改什么"与"未验证与已知缺口"

矩阵本身的修正不在本分支：它由维护者在 dot-skill-test 的 52d4050 落地（见 §4），本分支只按修正后的事实用它。
src/hosts/agents.mjs 未被本分支改动。

2. 测试命令与结果

2.1 主断言

$ node --test tests/agents.test.mjs
ok 1 - matrix shape: 8 unique hosts, each with a global path and a bilingual note
ok 2 - bin/distilly.mjs hosts table matches the matrix host-for-host
ok 3 - only DeepSeek Harness lacks an AgentSkills CLI target, and its error names the clone route
ok 4 - cloneCommand("project") fails for global-only hosts and targets the documented dir
ok 5 - every emitted command uses the current repo and skill name
# tests 5 / pass 5 / fail 0

node --test（不指定文件）同样 5/5：本分支上 tests/ 里目前只有这一个 .mjs，Python 测试由 ds/01 迁移。

逐条对应任务要求：

要求 落在哪条断言 结果
AGENTS.length === 8、id 唯一、每个有 globalPath 与非空双语 note 1 通过
bin/distilly.mjs 的 hosts 表与矩阵一一对应（含 $DSH_HOME / ~/.dsh 等价） 2 通过
skillsCliSupported('pi')、严格模式抛错与"其余 7 个通过" 3 通过（按修正后的事实：CLI 可用 7 个 = claude-code / codex / opencode / openclaw / hermes / grok-build / pi；clone-only 1 个 = deepseek-harness，严格模式抛错且错误信息含 cloneCommand('deepseek-harness', 'global')）
cloneCommand(id,'project')：无项目级目录的宿主抛错，其余指向该目录 4 通过（无项目级目录的只剩 openclaw；pi 在 52d4050 后有了 .pi/skills/distilly）
命令串含 titanwings/distilly、--skill distilly、无旧仓库名 5 通过（同时禁止 dot-skill、colleague-skill、python3 ）

与任务原始写法的偏差（事实变了，不是放宽）：原要求写"pi 不支持、openclaw 和 pi 没有项目级目录"。维护者 52d4050 用上游注册表复核后，pi 是合法目标并补了项目级目录，deepseek-harness 才是唯一没有上游目标的宿主；测试按新事实写，能力集合大小仍是 7 + 1。

2.2 反向对照（证明断言真的会红）

把 bin/distilly.mjs 复制到 /tmp/agents-mutation/ 做变异，测试文件与矩阵不动：

变异 结果
A：安装器把 codex 写到 ~/.codex/skills/distilly not ok 2，bin/distilly.mjs installs codex to ~/.codex/skills/distilly, the matrix says ~/.agents/skills/distilly；4 pass / 1 fail
B：删掉安装器的 openclaw 条目 not ok 2，bin/distilly.mjs and src/hosts/agents.mjs must list the same hosts；4 pass / 1 fail

2.3 可选的 cliId 复核脚本

$ node scripts/check-agent-ids.mjs
skipped: upstream skills CLI unavailable
exit=0

$ SKILLS_CLI=<本地上游 cli.mjs> node scripts/check-agent-ids.mjs
upstream skills CLI: … v1.5.26
ok   claude-code        --agent claude-code
ok   codex              --agent codex
ok   opencode           --agent opencode
ok   openclaw           --agent openclaw
ok   hermes             --agent hermes-agent
ok   grok-build         --agent grok
ok   pi                 --agent pi
checked 7 cliId targets: 7 valid, 0 invalid
clone-only (no upstream target): deepseek-harness
exit=0

把矩阵里的 grok 改回 grok-build 再跑：FAIL grok-build --agent grok-build、6 valid, 1 invalid、exit 1 —— 失败路径有效。

2.4 上游复现命令

$ npx skills@1.5.26 ls -a grok              # exit 0，合法
$ npx skills@1.5.26 ls -a hermes-agent      # exit 0，合法
$ npx skills@1.5.26 ls -a pi                # exit 0，合法
$ npx skills@1.5.26 ls -a grok-build        # exit 1，Invalid agents: grok-build
$ npx skills@1.5.26 ls -a hermes            # exit 1，Invalid agents: hermes
$ npx skills@1.5.26 ls -a deepseek-harness  # exit 1，Invalid agents: deepseek-harness

本机实际执行的是同一份 skills@1.5.26 包离线解包后的 node dist/cli.mjs ls -a <id>（HOME 指向临时目录、DISABLE_TELEMETRY=1），输出与上表逐字一致；合法 id 全表在包内注册表
（dist/cli.mjs 的 grok: 定义、hermes-agent: 定义、package.json 的 keywords），非法 id 会打印 Invalid agents: … 并列出 Valid agents: 全表（78 项，其中没有 grok-build / hermes / deepseek* / dsh）。

3. 宿主表 before → after

3.1 文档里的宿主数量

旧文档 现在
README.md 宿主墙 8 个（Claude Code / Hermes Agent / OpenClaw / Codex / DeepSeek Harness / Pi coding agent / Grok Build / OpenCode）+ Grok Bot 预览说明 不变（README 只改安装段）
INSTALL.md「兼容宿主」 8 个 不变，但顶部新增 v2 入口并整节标 Deprecated
INSTALL_EN.md 宿主表 8 行 不变，同上
src/hosts/agents.mjs 8 条 8 条（52d4050 只改 cliId 并给 Pi 补 projectPath，不增删宿主）
docs/v2/HOSTS.md 不存在 8 行 × 8 列 + clone 路线表 + 换宿主指南 + 缺口表
Grok Bot 旧文档写「预览，不能一键安装」 仍然不在矩阵内（依据 INSTALL.md:292-296），并在 HOSTS.md 里显式说明

路径纠正：0 处。 8 个宿主的 globalPath 与 bin/distilly.mjs（第 32–45 行）以及 INSTALL.md / INSTALL_EN.md 的原表本来就一致，本次没有发现路径级事实错误。旧文档里"或 ~/.agents/skills/distilly"这类备选写法（Pi、Grok Build）没有删除，只是在矩阵里收敛为一个 canonical 目标：Pi=~/.pi/agent/skills/distilly、Grok Build=~/.grok/skills/distilly。

3.2 真正被纠正的是 cliId（维护者 52d4050）

矩阵注释自称 cliId 是"--agent target, only when confirmed"，但四个值对上游注册表不成立：

宿主 before after 依据（上游 skills@1.5.26）
Hermes cliId: 'hermes' ❌ 'hermes-agent' ✅ ls -a hermes → Invalid agents: hermes；ls -a hermes-agent → exit 0
Grok Build cliId: 'grok-build' ❌ 'grok' ✅ ls -a grok-build → Invalid agents: grok-build；ls -a grok → exit 0（该条目 displayName 就是 "Grok Build"，全局目录 ~/.grok/skills，与矩阵 globalPath 一致）
Pi 无 cliId，note 写"--agent 目标未确认" ❌ cliId: 'pi' ✅，并补 projectPath: '.pi/skills/distilly' ls -a pi → exit 0；注册表里项目级 .pi/skills、全局 ~/.pi/agent/skills
DeepSeek Harness cliId: 'deepseek-harness' ❌ 删除 cliId → 仅 clone 路线 78 个合法目标里没有 DSH / deepseek；ls -a deepseek-harness → Invalid agents:

影响：修正前 skillsCliCommand('grok-build' | 'hermes' | 'deepseek-harness', …) 会输出上游直接拒绝的 --agent，即文档承诺的命令跑不起来。修正后 7 个宿主严格模式通过、DSH 抛错并指向 cloneCommand。能力集合大小仍是 7 + 1，只是成员换了。

4. 已知缺口与未验证项

# 项 状态 依据 / 说明
1 8 个宿主"怎么验证装上了" 未在真机复核 本机 PATH 无 claude / opencode / openclaw / hermes / pi / grok；只有 /opt/homebrew/bin/codex（codex-cli 0.146.0），实测 codex --help 没有 skills 子命令，所以 Codex 只能进会话看 /skills。HOSTS.md 的验证列全部来自本仓库文档并逐条标注行号
2 Codex 全局目录到底是 ~/.agents/skills 还是 ~/.codex/skills 未定论，本 PR 不改 本矩阵、INSTALL.md:213、bin/distilly.mjs:38 一致写 ~/.agents/skills；上游 skills@1.5.26 把 .agents/skills 当共享发现目录（出现 38 次），但它自己的 codex 条目 globalSkillsDir = $CODEX_HOME/skills（默认 ~/.codex/skills，dist/cli.mjs:1352、1530）。要改必须同时动 bin/distilly.mjs（牵动 ds/01 安装器与 CI）→ follow-up 建议：由一个能开真 codex 会话的分支实测"装到 ~/.agents/skills 能否被 Codex 发现"，有结论后再决定是否统一三个目标
3 Hermes CLI 路线的落点 未验证 上游 hermes-agent 全局目录是 ~/.hermes/skills，本矩阵 globalPath 是 ~/.hermes/skills/openclaw-imports/distilly（INSTALL_EN.md:66、tools/install_hermes_skill.py:48）。两条路线可能落在同一 skills 根的不同子目录，没在真机 hermes skills list 里比对过
4 npx skills add 真机安装后宿主是否真的发现 未验证 仓库里没有 AgentSkills CLI 真机安装记录；矩阵只保证"目标是上游合法 --agent 值"
5 claude plugin list 未验证 / 可能不适用 无 claude 可执行文件；且 clone 安装的 Skill 不是 Claude Code 插件，这条命令能否列出它没有依据，HOSTS.md 里明确标"未验证"
6 npm test 汇总入口 本分支没有 package.json 目前只有 prepack，npm test 由 ds/01 落地；本 PR 的验收命令是 node --test tests/agents.test.mjs
7 上游 --agent 改名风险 已缓解，未进 CI scripts/check-agent-ids.mjs 可本地复核；按约定不进 CI、不联网安装，因此不会在上游改名时自动报警

5. 回滚

按提交逆序 revert 即可，互不依赖：

git revert a06e5ef   # docs(v2): HOSTS.md
git revert e7700d9   # docs: INSTALL/INSTALL_EN/README 宿主章节
git revert 7c095ea   # chore(scripts): check-agent-ids.mjs
git revert 7b24bde   # test(v2): tests/agents.test.mjs
  • 只回滚文档、测试与可选脚本，不动 src/hosts/agents.mjs、bin/distilly.mjs 或任何运行时路径，宿主安装行为不变。
  • 若只想撤销"指向 HOSTS.md"，revert e7700d9 一处即可：INSTALL/INSTALL_EN/README 会回到旧的按平台说明。
  • 矩阵修正 52d4050 在集成分支上，回滚它需要单独 revert；本分支不依赖它的提交历史，只依赖它的字段值。

@titanwings
feat(v2): add the coding-agent support matrix as shared host data
33ac9b3 
重建说明：本提交由会话转录重建，提交信息取自原分支（ds/05-agents）。
文件内容为集成分支上的最终态，不是当时那一刻的中间态——原分支的 per-commit
文件树随 /tmp 清空丢失，转录只保留了提交信息与 git add 的路径清单。

原提交信息：feat(v2): add the coding-agent support matrix as shared host data
@titanwings
chore(agents.test): 重建 tests/agents.test.mjs（原提交信息未记录）
a9b5157 
重建说明：本提交由会话转录重建，提交信息取自原分支（ds/05-agents）。
文件内容为集成分支上的最终态，不是当时那一刻的中间态——原分支的 per-commit
文件树随 /tmp 清空丢失，转录只保留了提交信息与 git add 的路径清单。

原提交信息：(未记录)
@titanwings
chore(check-agent-ids): 重建 scripts/check-agent-ids.mjs（原提交信息未记录）
a485306 
重建说明：本提交由会话转录重建，提交信息取自原分支（ds/05-agents）。
文件内容为集成分支上的最终态，不是当时那一刻的中间态——原分支的 per-commit
文件树随 /tmp 清空丢失，转录只保留了提交信息与 git add 的路径清单。

原提交信息：(未记录)
@titanwings
chore(v2): 重建 docs/v2/HOSTS.md（原提交信息未记录）
e52726f 
重建说明：本提交由会话转录重建，提交信息取自原分支（ds/05-agents）。
文件内容为集成分支上的最终态，不是当时那一刻的中间态——原分支的 per-commit
文件树随 /tmp 清空丢失，转录只保留了提交信息与 git add 的路径清单。

原提交信息：(未记录)
@titanwings
chore(evidence): 重建 docs/evidence/pr-05-agents.md（原提交信息未记录）
fd3db7d 
重建说明：本提交由会话转录重建，提交信息取自原分支（ds/05-agents）。
文件内容为集成分支上的最终态，不是当时那一刻的中间态——原分支的 per-commit
文件树随 /tmp 清空丢失，转录只保留了提交信息与 git add 的路径清单。

原提交信息：(未记录)
@titanwings
titanwings force-pushed the ds/02-parse-zero-cred branch from b46f950 to cc0ead2 Compare September 15, 2026 09:35
@titanwings titanwings closed this Sep 15, 2026
@titanwings titanwings reopened this Sep 15, 2026
dsh-agent
ci: 触发名单加 ds/**（本分支此前永远跑不到 CI）
85c65d6 
这 19 个 PR 是堆叠的，base 是上一条 ds/* 分支，而 CI 的触发名单只有
[dot-skill-test, dot-skill, main]，所以本分支的 push / PR 都不会触发工作流，
PR 页面永远显示 no checks reported。这里只改触发条件，不动任何产品代码。
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@titanwings