AgentForge
lixiuxiu559/agentforge
Claude Code 플러그인과 DSH 플러그인 양쪽으로 설치되는 단일 저장소: 6개의 엔지니어링 스킬(리서치, 아키텍처 탐색, 구현 오케스트레이션, 3축 diff 리뷰, 복잡도 감사, 뮤테이션 테스트)와 5개 서브에이전트를 디스패치하는 agentforge 도구 하나를 제공합니다.
설치
dsh plugin --profile web add github:lixiuxiu559/agentforgeREADME
AgentForge
通用 agent 工作流与工程技能集，作为可安装的 Claude Code 插件与 DeepSeek Harness 插件。 零外部依赖 —— 不使用 MCP，不依赖网络，不依赖项目预装工具。
一份真源，两端原生可用：skills/ 与 agents/ 在磁盘上只有一份。
Claude Code 走原生自动发现，DSH 走包内桥接插件（src/index.js）。
安装
Claude Code
claude plugin marketplace add Lixiuxiu559/AgentForge
claude plugin install agentforge@agentforge
在 Claude Code 交互界面里对应：
/plugin marketplace add Lixiuxiu559/AgentForge
/plugin install agentforge@agentforge
安装后重启 Claude Code 使其生效。
本地开发时可以装本地目录（原位加载，改动立即生效，不受版本号约束）：
claude plugin marketplace add /path/to/AgentForge
claude plugin install agentforge@agentforge
其他常用命令：
claude plugin list # 已装插件
claude plugin details agentforge # 组件清单与 token 成本
claude plugin update agentforge@agentforge # 更新到新版本
claude plugin disable agentforge # 临时停用
claude plugin uninstall agentforge # 卸载
DeepSeek Harness
从 npm 装（推荐 —— 按版本号升级，不受 main 分支变动影响）：
dsh plugin --profile web add dsh-agentforge
dsh plugin 是 pnpm 的转发器：它在 profile 目录（$DSH_HOME/profiles/<name>）里执行
pnpm <你的参数>，然后读回 profile 的 package.json —— 凡是解析到声明了 dsh.bundle
的依赖，就自动追加进 dsh.profile.bundles 层栈（本仓库已声明，见 package.json）。
所以参数可以是 pnpm 接受的任何 spec：
| 装法 | 命令 | 升级语义 |
|---|---|---|
| npm | dsh plugin --profile web add dsh-agentforge | 按 version 解析，发版才动 |
| GitHub 简写 | dsh plugin --profile web add github:Lixiuxiu559/AgentForge | 钉 commit，update 会跟到 main 最新提交 |
| 钉 tag | dsh plugin --profile web add github:Lixiuxiu559/AgentForge#v0.4.1 | 钉该 tag 的 commit，不受分支影响 |
| 本地目录（开发用） | dsh plugin --profile web add /path/to/AgentForge | 直接读磁盘，改动立即生效 |
⚠️ git 安装没有版本门控：lockfile 里钉的是具体 commit，
dsh plugin --profile web update会重解析到分支最新提交——等于「push 即发布」。想要版本门控请用 npm。
装完后重启该 profile（patchReload: live 只监听用户 patch 文件，不会重新 apply()）。
本仓库没有 prepare 脚本，任何装法都不需要 allowBuilds 构建授权。
升级 / 卸载：
dsh plugin --profile web update dsh-agentforge # 升级到符合 semver 范围的新版本
dsh plugin --profile web remove dsh-agentforge # 卸载
验证装配（不启动模型，只看组合后的插件树）：
dsh --profile web --dump-config | grep -A2 agentforge
已经用
link:或 git 装过的，先dsh plugin --profile web remove agentforge（或… remove dsh-agentforge）再按上面的 npm 方式重装，否则 profile 里会同时留着旧记录。
装什么
技能（6）
| 技能 | 作用 |
|---|---|
research | 调研与调查：技术研究、代码库调查、日志排查、证据链与研究报告 |
architecture-scout | 用户主动发起的架构机会侦察：按需并行委派 researcher 收集证据，主 Agent 筛选模块边界；允许零候选，不修改代码 |
diff-review | 三轴代码评审：Correctness（有 bug 吗）+ Standards（符合本仓库编码规范吗）+ Spec（忠实实现需求吗），各轴独立报告。能力自包含，不依赖任何宿主 |
implementation-workflow | 实施编排：评估任务、拆分依赖、串行/并行调度 implementer、集成验证、按风险调用审计 agent |
complexity-audit | 复杂度风险审计：用 CRAP 定位「复杂且测试保护不足」的函数，支持 Java / Python / Go / JS / TS |
mutation-testing | 测试有效性审计：用突变测试找出存活突变体与无覆盖代码，支持 Java / Python / Go / JS / TS |
子 agent（5）
| Agent | 职责 | 工具边界 |
|---|---|---|
researcher | 技术调研、代码调查、日志排查、证据收集与研究报告 | Read / Glob / Grep / Edit / Write / Bash / WebSearch / WebFetch |
diff-reviewer | 三轴评审执行者（Correctness + Standards + Spec） | 只读：Read / Glob / Grep / Bash |
implementer | 阅读代码、修改实现、编写测试、局部验证 | Read / Glob / Grep / Edit / Write / Bash |
complexity-auditor | 复杂度与覆盖率风险审计 | 只读：Read / Glob / Grep / Bash |
mutation-auditor | 突变测试与测试有效性审计 | 只读：Read / Glob / Grep / Bash |
三个只读 agent（diff-reviewer / complexity-auditor / mutation-auditor）只报告、不改码，从工具层面保证「发现问题」和「实施修复」解耦。
researcher 默认只调查不修改，用户要求长报告时才写入 docs/research/。
同一个插件在两端的形态
| 组件 | Claude Code | DeepSeek Harness |
|---|---|---|
| 技能（6） | 自动发现 skills/<name>/SKILL.md | 桥接插件注册为 skill provider，模型目录与 / 命令面板都可见 |
| 子 agent（5） | 自动发现 agents/<name>.md | 桥接插件注册一个 agentforge 工具，用 agent 参数枚举选择 |
| 工具边界 | agent frontmatter 的 tools: 白名单 | 同一份白名单，经 CC→DSH 工具名映射后由 toolFilter 强制 |
| 系统提示词 | agent 正文即子 agent 的系统提示词 | 同一份正文作为 persona 传入 |
只有一个工具：DSH 侧不注册 5 个同名工具，而是注册 1 个 agentforge，
工具描述里列出全部 agent 与职责，agent 参数用 enum 约束。新增 agent 只需加一个
markdown 文件，不用改 YAML —— 但要重载插件：工具描述与 enum 在 apply() 时固定，
不像技能那样按需重扫。
工具名不叫
subagent：DSH 的 dsh-base 已经注册了subagent/subagent_fork， 重名会让插件装载直接失败。可用 patch 行的config.toolName改名。
DSH 侧的两端差异（已适配）
| 差异 | 处理方式 |
|---|---|
工具名两套命名（Read vs read） | 桥接插件做映射；未映射的名字会被丢弃并记 warning |
model: haiku / sonnet 是 Claude Code 别名 | DSH 侧默认忽略（子 agent 继承父会话路由）；需要固定路由时用 config.agents.<name> |
maxTurns | 刻意不使用 —— 超限时输出被静默截断（对只读审计会造假阴性），且 DSH 无对应物。doctor 会拦截。见 docs/architecture.md §A.6 |
${CLAUDE_PLUGIN_ROOT} 是 CC 的变量 | 注册技能正文 / 子 agent persona 时展开成真实包路径 |
agent 正文里的 skills/... 相对路径 | 子 agent persona 前置一段「AgentForge 资源位置」，写明插件根目录 |
CC 的 hooks/hooks.json | 未实现（本仓库当前没有 hooks 资产，不做空桥） |
token 成本
实测（claude plugin details agentforge，v0.2.1）：
Always-on: ~308 tok # 10 个组件的 description 总和，加到每个会话
技能正文与子 agent 定义按需加载，几个参考值：
| 组件 | on-invoke |
|---|---|
diff-reviewer | ~1.1k |
implementation-workflow | ~790 |
diff-review | ~740 |
complexity-audit | ~640 |
research | ~540 |
mutation-testing | ~530 |
DSH 侧的常驻成本是六个技能的 description 加一个 agentforge 工具签名（工具描述列出五个 agent 的职责）。以上 v0.2.1 的 token 数值属于历史快照，新增 architecture-scout 后未重新实测，不能当作当前精确值。
五个 agent 如何配合
researcher ← 上游：获取事实与证据
│ 技术调研 / 代码调查 / 日志排查
↓
结论 + 证据链
│
↓
implementation-workflow ← 中游：实施编排
├─ 评估规模与风险
├─ 拆分任务、判断串行/并行
├─ 派发 implementer
├─ 集成 + 统一验证
├─ 按风险 → diff-reviewer
├─ 按风险 → complexity-auditor
└─ 按风险 → mutation-auditor
↓
implementer 修复
↓
重新验证
质量门不是每次都跑全套：按变更风险在 diff-reviewer / complexity-auditor /
mutation-auditor 之间选择；跳过任何一个都要在报告里说明原因，缺工具时如实降级。
判定表以 skills/implementation-workflow/references/quality-gates.md
为准 —— 本文件不再复制一份，避免两处漂移。
典型用法
Claude Code：
# 调研
/research 对比一下几个 Java 的 mutation testing 工具
# 开工前架构机会侦察（允许结论为暂无值得改造的地方）
/architecture-scout 怎样让接下来的订单模块改动更容易？
# 实施
/implementation-workflow 给用户模块加上导出功能
# 提交前三轴评审
/diff-review 看一下这次改动
# 单独审计
/complexity-audit 检查一下这次改动
/mutation-testing 验证 task 模块的测试有效性
DeepSeek Harness：技能同样按 description 触发，也可以直接点名。
用 architecture-scout 技能调查订单模块的边界，必要时并行委派 researcher 取证；只出候选报告，不修改代码。
用 research 技能对比一下几个 Java 的 mutation testing 工具
用 agentforge 工具，agent=researcher，去查清 task 模块的测试覆盖情况
用 agentforge 工具，agent=diff-reviewer，三轴评审这次改动
用 agentforge 工具，agent=complexity-auditor，审计这次改动
DSH 侧的子 agent 通过 agentforge 工具调用；implementation-workflow 技能里的
「派发 implementer」「调用 diff-reviewer」在两端都指向同一份 agent 定义。
diff-review 技能与 diff-reviewer agent 同源：技能由主 Agent 自己执行，
agent 用隔离上下文执行同一套三轴方法。
目录结构
AgentForge/
├── .claude-plugin/
│ ├── plugin.json # CC 插件清单（version 是发版开关）
│ └── marketplace.json # CC 市场清单（source: "./"）
│
├── package.json # DSH bundle 清单 + npm 元数据
├── cordis.patch.yml # DSH layer：挂一行桥接插件
├── src/index.js # ★ 唯一代码：DSH 桥接插件（零依赖纯 JS）
│
├── skills/ # ★ 真源，两端读同一份
│ ├── research/SKILL.md
│ ├── architecture-scout/ # 架构机会侦察；含判据、并行调查与报告模板
│ │ ├── SKILL.md
│ │ └── references/
│ ├── diff-review/ # Correctness / Standards / Spec 三轴评审
│ │ ├── SKILL.md
│ │ └── references/
│ ├── implementation-workflow/
│ │ ├── SKILL.md # 编排入口
│ │ └── references/ # 拆分 / 并行 / 质量门 / 任务卡模板
│ ├── complexity-audit/
│ │ ├── SKILL.md
│ │ ├── scripts/crap.js # Java + JaCoCo 的 CRAP 计算器
│ │ └── references/ # 五语言适配
│ └── mutation-testing/
│ ├── SKILL.md
│ └── references/ # 五语言适配
│
├── agents/ # ★ 真源：CC 自动发现，DSH 由桥接插件注册
│ ├── researcher.md
│ ├── diff-reviewer.md
│ ├── implementer.md
│ ├── complexity-auditor.md
│ └── mutation-auditor.md
│
├── tools/
│ ├── doctor.mjs # 结构与资产校验 + DSH 适配校验（零依赖）
│ └── release.mjs # 发版脚本
├── .github/workflows/validate.yml # push 时校验，不发版
├── CHANGELOG.md
└── docs/
├── architecture.md # 架构决策与实测结论
└── releasing.md # 发布流程
校验
node tools/doctor.mjs
检查以下几类；其中 dsh 组是双端适配校验（CC 侧改坏、DSH 侧静默失灵都能抓到）：
| 检查 | 抓什么 |
|---|---|
manifest | 插件/市场清单缺失、JSON 非法、name 非 kebab-case、市场未声明插件 |
layout | 组件目录被误放进 .claude-plugin/（不会被发现） |
skills | frontmatter 缺失、name 与目录名不一致、嵌套技能、references/ 悬空引用 |
agents | frontmatter 缺失、name 与文件名不一致 |
agents | 声明了 maxTurns（本仓库刻意不用，见 §A.6） |
agents | 只读 agent 却声明了 Edit/Write |
agents | 任何 mcp__* 依赖（本插件承诺零外部依赖） |
paths | 硬编码绝对路径（应用 ${CLAUDE_PLUGIN_ROOT}） |
dsh | dsh.bundle.patch 缺失/指向不存在的文件、patch 里没出现包名 |
dsh | src/index.js 缺失或无法加载、未导出映射表 |
dsh | agent 声明的工具在 DSH 无对应物（会被静默丢弃） |
dsh | 桥接插件的工具名与 DSH 保留名冲突 |
dsh | CC 专属字段（model）在 DSH 被忽略（info） |
dsh 组直接 import src/index.js 读取工具名映射表，不抄第二份，避免漂移。
退出码非 0 表示存在 error，已接进 CI。
也可以用官方校验器：
claude plugin validate .
发版
version 就是发版开关。 不 bump 它，用户收不到任何更新——所以日常 push 和发版是解耦的。
# 日常开发：随便 push，用户无感知
git push
# 发版：显式动作
node tools/release.mjs patch # 0.1.1 → 0.1.2
git push --follow-tags
release.mjs 会依次检查工作区、分支、校验、tag 冲突、CHANGELOG，然后 bump 版本、更新 CHANGELOG、提交、打标签。支持 --dry-run 和 --push。
版本号判据是**「对使用者是否破坏」**：重命名或删除技能/agent 属 MAJOR，新增能力属 MINOR，措辞与脚本修复属 PATCH。
完整规范见 docs/releasing.md，版本历史见 CHANGELOG.md。
设计约束
- 零外部依赖 —— 不使用 MCP，不依赖网络，不依赖项目预装工具。
- 只读边界 —— 审计类 agent 不持有 Edit/Write，从工具层面保证「只报告不改码」。
- 调查可追溯 ——
researcher必须区分事实、推断、未确认项和置信度；长报告保存到docs/research/。 - 技能是方法，agent 是角色 —— 技能承载可复用流程，agent 承载执行边界与权限。
- 详细规则下沉 —— 主
SKILL.md只留决策入口，细节放references/，避免上下文膨胀。 - 一份真源，两侧适配 ——
skills/、agents/只有一份；两端差异（工具名、路径变量、 模型别名）全部收在src/index.js的桥接层里解决，不往内容里塞条件分支。