hicode Coding Agent Plugin

1. 定位

本仓库根目录是 hicode 的设计中心，也是面向 Claude Code 与 Codex 的 plugin root，并提供 OpenCode agents/skills 和 Moss learned-skills 安装入口。

Claude Code 通过 plugin marketplace 安装；OpenCode 通过 install.sh --opencode 把 hicode 的 agents 和 skills 转换复制到 OpenCode 用户级或项目级目录；Codex 通过 install.sh --codex 把 hicode 作为 .codex-plugin plugin bundle 写入本地 marketplace 并执行 codex plugin add；Moss 通过 node scripts/install.js --moss 安装到 Moss 的 learned-skills 目录。

本 plugin 安装动作不执行目标项目初始化，不扫描代码，不生成 CLAUDE.md、AGENTS.md 或项目本地运行目录。

目标项目初始化由 hicode:init 在用户确认写入范围后执行，只创建或补充目标项目入口、上下文和项目规则文档。

---

2. 目录结构

/
├── README.md
├── install.sh
├── install.ps1
├── scripts/
│   ├── install.js
│   ├── install-codex.js
│   └── install-opencode.js
├── .claude-plugin/
│   ├── marketplace.json
│   └── plugin.json
├── .codex-plugin/
│   └── plugin.json
├── agents/
├── skills/
│   ├── hi/
│   ├── init/
│   ├── scope/
│   ├── tdd/
│   ├── review/
│   └── release/
└── hooks/

---

3. 安装范围

安装器采用跨平台双入口：

1. Linux、macOS、WSL、Git Bash、MSYS 和 Cygwin 使用 ./install.sh。 2. Windows PowerShell 使用 pwsh ./install.ps1。 3. 两个入口都委托 node scripts/install.js 执行相同安装逻辑；也可以直接运行 node scripts/install.js。

前置条件：本机需可执行 node；按安装目标分别需要已安装 claude、codex 或 OpenCode 对应运行环境。--dry-run 不调用目标平台 CLI。

支持的安装目标

| 目标 | 参数 | 说明 | |------|------|------| | Claude Code | --claude-code（默认） | 注册为 hicode Claude Code plugin | | OpenCode | --opencode | 安装 hicode-* Skill 和 Agent 到 OpenCode | | Codex CLI | --codex | 安装为 Codex .codex-plugin bundle | | Moss | --moss | 安装到 Moss learned-skills + 启用 config.yaml | | 全平台 | --all | 以上四个目标同时安装 |

install.sh / install.ps1 默认执行用户级安装：

1. 注册本地 hicode marketplace。 2. 安装 hicode Claude Code plugin。 3. 提供 8 个专业 Agent、hi 总入口、init 初始化入口和 scope、tdd、review、release 四个能力 Skill；场景路由表达保留为 hicode:init、hicode:scope、hicode:tdd、hicode:review 和 hicode:release。

OpenCode 安装使用显式参数：

1. ./install.sh --opencode --yes：安装到当前用户 OpenCode 配置目录。 2. ./install.sh --opencode --opencode-scope project --opencode-project-dir /path/to/project --yes：安装到目标项目 .opencode/ 目录。 3. Windows PowerShell 下使用等价参数：pwsh ./install.ps1 -OpenCode -Yes。

Codex 安装使用显式参数：

1. ./install.sh --codex --yes：复制 .codex-plugin/ 和 skills/ plugin bundle 到 ~/plugins/hicode，更新 ~/.agents/plugins/marketplace.json，并执行 codex plugin add hicode@<marketplace>。 2. ./install.sh --codex --codex-scope project --codex-project-dir /path/to/project --yes：复制 .codex-plugin/ 和 skills/ plugin bundle 到目标项目 plugins/hicode，更新目标项目 .agents/plugins/marketplace.json，并在目标项目目录执行 codex plugin add hicode@<marketplace>。 3. ./install.sh --all --yes：同时安装 Claude Code plugin、OpenCode 本地运行资产、Codex plugin 和 Moss。 4. Windows PowerShell 下使用等价参数：pwsh ./install.ps1 -Codex -Yes、pwsh ./install.ps1 -All -Yes。

Moss 安装使用显式参数：

1. ./install.sh --moss --yes：将 6 个 Skill + 8 个 Agent 安装到 ~/.moss/agents/zhangdalong/learned-skills/，并追加到 config.yaml 的 skills.enabled 列表。 2. ./install.sh --moss --moss-agent-id <id> --yes：指定 Agent ID（默认 zhangdalong）。 3. ./install.sh --check：验证 Moss 端 hicode 技能是否已安装并启用。

卸载使用 --uninstall 搭配同一组平台和 scope 参数：

1. ./install.sh --uninstall --claude-code --yes：调用 claude plugin uninstall hicode@hicode。 2. ./install.sh --uninstall --opencode --yes：只删除 OpenCode 目录下安装器生成的 hicode- Skill 和 Agent。 3. ./install.sh --uninstall --codex --yes：调用 codex plugin remove hicode@<marketplace>，并删除本地 marketplace 条目和 plugins/hicode bundle。 4. ./install.sh --uninstall --moss --yes：删除 Moss learned-skills 目录下的 hicode- 目录，并从 config.yaml 移除对应条目。 5. ./install.sh --uninstall --all --yes：同时卸载所有平台资产。

Claude Code 或 Codex CLI 返回 plugin 已不存在时，卸载视为幂等成功并继续清理其他 hicode-owned 资产；其他命令错误仍会失败。

安装器不修改业务仓库，不读取生产配置，不处理生产数据或客户敏感信息。

目标项目初始化应在业务仓库中显式调用 hicode:init。默认只创建或补充 CLAUDE.md / AGENTS.md、项目上下文和 RULES 文档；不复制 plugin 内置能力到目标项目运行目录。

---

4. 使用示例

# 安装到各平台
./install.sh --dry-run
./install.sh --opencode --dry-run
./install.sh --codex --dry-run
./install.sh --moss --dry-run
./install.sh --all --dry-run
./install.sh --uninstall --all --dry-run
./install.sh --yes
node scripts/install.js --all --dry-run --yes
bash scripts/health-check.sh

# Moss 安装与验证
node scripts/install.js --moss --yes   # 安装
# 重启 Moss server 后...
node scripts/install.js --check        # 验证

Windows PowerShell：

pwsh ./install.ps1 -DryRun
pwsh ./install.ps1 -OpenCode -DryRun
pwsh ./install.ps1 -Codex -DryRun
pwsh ./install.ps1 -Moss -DryRun
pwsh ./install.ps1 -All -DryRun
pwsh ./install.ps1 -Uninstall -All -DryRun
pwsh ./install.ps1 -Yes

不传平台参数时默认安装 Claude Code plugin。

scripts/health-check.sh 用于重复验证当前运行资产边界、安装边界、旧路径依赖、安全红线和 Agent 共性规则收敛情况；它不扫描目标项目，不读取敏感配置或生产数据。

---

5. Moss 安装备忘

前置知识

| 概念 | 说明 | |---|---| | SKILL.md | 每个技能是一个目录，内含 SKILL.md 文件 | | 目录名 = name 字段 | 目录名必须和 SKILL.md 的 name frontmatter 一致 | | 安装位置 | ~/.moss/agents/<agent-id>/learned-skills/<skill-name>/SKILL.md | | 启用开关 | ~/.moss/agents/<agent-id>/config.yaml 的 skills.enabled 列表 | | 生效条件 | 修改 config.yaml 后必须重启 Moss server |

安装命令

cd /path/to/hicode
node scripts/install.js --moss          # 安装
# 重启 Moss server（关闭桌面端重开，或 kill server 进程）
# kill $(pgrep -f "server/bootstrap.js" | tail -1)
node scripts/install.js --check          # 验证

--moss 做了三件事：

1. 复制文件到 learned-skills 目录 2. 修正 SKILL.md 的 name 字段（目录名 = name） 3. 追加到 config.yaml 的 skills.enabled 列表

> ⚠️ 安装后必须重启 Moss server，否则 config.yaml 的改动用不上。

手动安装步骤（备用）

# 1. 安装 Skill 文件
for skill in hi init scope tdd review release; do
  mkdir -p ~/.moss/agents/zhangdalong/learned-skills/hicode-$skill
  cp -R hicode/skills/$skill/. ~/.moss/agents/zhangdalong/learned-skills/hicode-$skill/
done

for agent in requirement-reviewer coding-planner tdd-guide coding-assistant \
             code-reviewer security-reviewer java-reviewer release-reviewer; do
  mkdir -p ~/.moss/agents/zhangdalong/learned-skills/hicode-agent-$agent
  cp hicode/agents/$agent.md ~/.moss/agents/zhangdalong/learned-skills/hicode-agent-$agent/SKILL.md
done

# 2. 修正 name 字段（目录名必须 = name）
for s in hi init scope tdd review release; do
  sk="$HOME/.moss/agents/zhangdalong/learned-skills/hicode-$s/SKILL.md"
  sed -i '' "s/^name:.*/name: hicode-$s/" "$sk"
done
for a in requirement-reviewer coding-planner tdd-guide coding-assistant \
         code-reviewer security-reviewer java-reviewer release-reviewer; do
  sed -i '' "s/^name:.*/name: hicode-agent-$a/" \
    "$HOME/.moss/agents/zhangdalong/learned-skills/hicode-agent-$a/SKILL.md"
done

# 3. 在 config.yaml 的 skills.enabled 列表添加 14 项
#    hicode-hi, hicode-init, hicode-scope, hicode-tdd, hicode-review, hicode-release,
#    hicode-agent-requirement-reviewer, hicode-agent-coding-planner, ...

# 4. 重启 Moss server

---

6. hicode Skill 速通指南

> 用盖房子的故事，搞懂 6 个 hicode skill 分别干什么、什么时候用、按什么顺序用。

6.1 一句话定位

| Skill | 盖房子比喻 | 一句话说明 | |---|---|---| | hi | 前台接待 | 不知道从哪开始？先找"hi"，它帮你指路 | | init | 打地基、通水电 | 新项目第一次用 hicode，先把基础设施搭好 | | scope | 画图纸、定方案 | 需求还没想清楚？先理清范围、拆成小任务 | | tdd | 一砖一瓦盖房子 | 需求清楚了，开始写代码（先写测试，再实现） | | review | 监理质检 | 代码写完了，检查有没有问题 | | release | 搬家验收 | 要上线了，检查能不能发、出问题了怎么回滚 |

6.2 使用顺序

标准流程（从 0 到上线）：

hi → init → scope → tdd → review → release

每一步的输出是下一步的输入：

hi 告诉你：项目还没初始化
  ↓
init 做完：项目有了入口和规则
  ↓
scope 做完：需求清楚了，拆成了小任务
  ↓
tdd 做完：代码写好了，测试通过了
  ↓
review 做完：代码审查通过，问题已修复
  ↓
release 做完：发布报告生成，可以上线了

常见场景速查：

| 你的状态 | 从哪个 skill 开始 | |---|---| | 第一次用 hicode，项目是新的 | hi → init → ... | | 项目已初始化，来了新需求 | scope → tdd → review | | 需求很清楚，直接开写 | tdd → review | | 代码写完了，想检查一下 | review | | 要上线了，检查风险 | release | | 只想了解 hicode 是什么 | hi |

可以跳过的场景：

只 review，不改代码 → 直接 review
只做发布检查 → 直接 release
项目已初始化好 → 跳过 init，从 scope 或 tdd 开始

不能跳过的场景：

没初始化就想写代码 → 必须 init，否则没有上下文和规则
需求没想清楚就写代码 → 必须 scope，否则容易写偏
没测试就 review → 可以 review，但证据轴会降级
没 review 就 release → 可以 release，但风险等级会很高

决策流程图：

你打开一个项目
    │
    ▼
只发了 hi？ ───→ 用 hi → 它帮你判断下一步
    │
    有明确任务？
    │
    ├── 项目没初始化 ─────→ 用 init
    ├── 需求来了但模糊 ───→ 用 scope
    ├── 任务明确了，写代码 ─→ 用 tdd
    ├── 代码写完了，要检查 ─→ 用 review
    └── 准备上线 ────────→ 用 release

6.3 每个 Skill 详解

6.3.1 `hi` —— 前台接待/导航员

什么时候找它？

第一次打开项目，不知道 hicode 能不能用
只输入了"hi"，想看看 hicode 能干什么
不确定该用哪个 skill

它会做什么？

检查项目有没有初始化（有没有 AGENTS.md、docs/ 等文件）
告诉你当前项目状态：未初始化 / 部分初始化 / 已初始化
帮你指路：你现在的情况，应该走 init、scope、tdd、review 还是 release？

> 你说："hi" → 它说："你的项目还没初始化，建议先跑 init。"

---

6.3.2 `init` —— 装修队（打地基、通水电）

什么时候找它？

一个新项目，第一次要用 hicode
缺少 Coding Agent 的入口文件（AGENTS.md / CLAUDE.md）
缺少项目上下文文档、规则文档

它会做什么？

创建或补充入口文件（AGENTS.md / CLAUDE.md）
建立项目文档目录（docs/rules/、docs/DOMAIN_KNOWLEDGE.md、docs/PROJ_CONTEXT.md）
让项目具备被 hicode 理解和操作的基础
判断项目复杂度，建议是否需要代码结构扫描
不会碰生产环境、不会读密钥、不会改你的业务代码

> 你说："在这个仓库初始化 hicode" → 它会创建必要的骨架文件。

---

6.3.3 `scope` —— 设计师（画图纸、定方案）

什么时候找它？

需求来了，但描述模糊（比如"做个用户系统"）
需求太大，不知道怎么拆成小任务
不确定验收标准是什么
准备编码前，想先理清思路

它会做什么？

评审需求：目标清楚吗？验收标准可测试吗？边界在哪？
追问模糊点：一次只问一个关键问题，帮你把需求想透
对比方案：给出 2-3 种实现路径，说明利弊
拆任务：把大需求拆成可独立验证的小任务
输出编码准入判断："可以开始写了"还是"还需要再想想"

> 你说："帮我梳理这个需求，拆成可编码任务" → 它会输出 scope-plan.md，包含设计树方案和 TDD 任务计划。

---

6.3.4 `tdd` —— 施工队（一砖一瓦盖房子）

什么时候找它？

任务已经拆好了（来自 scope），可以开始写代码了
需要修复一个 bug，需要先复现再修复
需要重构代码，但需要有测试保护

它会做什么？

按 RED → GREEN → REFACTOR 循环工作
一次只做一个行为，小步快跑，不贪多
测试验证公开接口的行为，不绑内部实现
每完成一个行为就验证一次
记录每轮的修改和结果

> 你说："按 TDD 实现 task 1" → 它会先写失败测试 → 跑测试确认失败 → 写最小实现 → 跑测试确认通过 → 记录 → 进入下一轮。

---

6.3.5 `review` —— 监理质检员

什么时候找它？

代码写完了，准备提交合并请求（MR/PR）
想检查代码有没有安全问题、性能问题
需要专项审查（Java 专项、SQL 审查、安全审查、保险业务审查）

它会做什么？

三轴审查：需求轴（实现是否符合需求？）、规范轴（编码/安全规范？）、证据轴（测试/CI 是否足够？）
专项检查：Java、SQL、权限、保险业务等
按严重程度（P0~P3）列出问题清单
给出阻断建议：哪些问题必须修了才能合并

> 你说："review 当前改动" → 它会分析 diff，输出问题清单和严重度排序。

---

6.3.6 `release` —— 搬家验收员

什么时候找它？

准备发布上线了
需要评估本次发布的风险
需要制定验证计划和回滚方案

它会做什么？

分析分支改动：这次改了哪些代码、配置、SQL？
核对需求文档和实现是否一致
汇总验证证据：测试通过了没有？Review 过了没有？
检查 SQL/配置/脚本风险：有没有幂等？能不能回滚？
生成发布报告：包含风险等级、验证计划、回滚方案

> 你说："分析当前分支的发布风险" → 它会输出发布报告，告诉你能不能发、有什么风险、出了问题怎么回滚。

---

6.4 8 个专业 Agent

这些 Agent 不需要手动调用——场景 Skill 会在需要时自动调派它们。

| Agent | 盖楼里的角色 | 负责什么 | 何时被调派 | |---|---|---|---| | coding-assistant | 全能工人 | 写代码、修 bug、重构 | tdd 需要实际改代码时 | | coding-planner | 施工规划师 | 制定实现计划 | scope 之后要写代码方案时 | | code-reviewer | 质检员 | 通用代码审查 | review 需要详细审查时 | | java-reviewer | Java 专家 | Java/Spring/SQL 专项 | 审查 Java 代码时 | | security-reviewer | 安检员 | 安全专项审查 | 发现安全风险时 | | requirement-reviewer | 产品经理 | 需求合理性审查 | scope 需要深度需求评审时 | | tdd-guide | TDD 教练 | 测试设计和测试代码 | tdd 需要设计测试时 | | release-reviewer | 发布管家 | 发布前综合检查 | release 需要详细分析时 |

---

6.5 注意事项

1. 每个 Skill 都有安全红线： 不看生产数据、不碰密钥、不自动发布、不自动合并。 2. 输出都是建议，不是审批： review 不替代人工审批，release 不代替发布决策。 3. 保险核心系统默认更严格： 涉及金额、状态流转、幂等、事务一致性的，风险评级默认更高。 4. 所有文档只记录事实： 不编造测试结果、不编造业务规则、不编造结论。

---

7. 安全边界

1. 不扫描目标项目代码。 2. 不生成目标项目入口文件。 3. 不生成或复制项目本地运行目录。 4. 不安装生产 Hook。 5. 不自动合并、自动发布、自动回滚或修改生产配置。 6. 不读取 .env、密钥文件、生产凭证或未脱敏客户数据。

---

8. 官方机制对齐

本仓库按以下官方机制组织：

1. Claude Code plugin 使用插件根目录下的 .claude-plugin/plugin.json、agents/ 和 skills/<name>/SKILL.md；当前 manifest 只声明 validator 支持的 skills 路径，agents/ 作为 plugin root 约定目录保留。 2. skills/init/coding_rules.md 是 hicode:init 创建或更新目标项目 docs/rules/ 的种子规则；其他场景 Skill 遵守目标项目规则文件。 3. 每个 skills/<skill>/ 目录只使用根目录文件承载本地具体模板和规则种子，不维护 Skill 内部子目录，也不为场景生命周期复制重复 README.md。 4. Agent 共性安全、权限、输出和停止条件写入各 Agent 正文，不再通过共享运行目录读取。 5. OpenCode 安装时将场景 Skill 转换为 hicode- Skill，将 agents/ 转换为 hicode-.md Agent，Agent 文件名即 OpenCode agent name。 6. Codex 安装时使用 .codex-plugin/plugin.json 和本地 marketplace；manifest 只声明 skills: "./skills/"，不声明 Codex manifest 不支持的 agents 字段，也暂不复制根目录 agents/。 7. Codex 安装不复制 docs/、archive/、agents/ 或历史资料。 8. 卸载只移除 hicode 明确拥有的插件、bundle、marketplace 条目和 hicode- OpenCode/Moss 资产，不删除目标项目入口、上下文文档、规则文档或业务代码。 9. hooks/ 只保留 Hook 行为说明和目录索引，不是目标平台默认上下文，也不维护与 skills/ 重复的规则或模板源。 10. Moss 安装在每个 Agent 的 learned-skills/ 目录下创建 hicode- 目录，内含 SKILL.md 及辅助文件；name frontmatter 必须和目录名一致；启用状态通过 config.yaml 的 skills.enabled 控制。

参考资料：

1. Claude Code Plugins：https://code.claude.com/docs/en/plugins#create-your-first-plugin 2. OpenCode Agent Skills：https://opencode.ai/docs/skills/ 3. Codex Plugins：https://developers.openai.com/codex/plugins 4. Codex Build Plugins：https://developers.openai.com/codex/plugins/build

hicode

Summary

Install to Claude Code

hicode Coding Agent Plugin

1. 定位

2. 目录结构

3. 安装范围

支持的安装目标

4. 使用示例

5. Moss 安装备忘

前置知识

安装命令

手动安装步骤（备用）

6. hicode Skill 速通指南

6.1 一句话定位

6.2 使用顺序

6.3 每个 Skill 详解

6.3.1 `hi` —— 前台接待/导航员

6.3.2 `init` —— 装修队（打地基、通水电）

6.3.3 `scope` —— 设计师（画图纸、定方案）

6.3.4 `tdd` —— 施工队（一砖一瓦盖房子）

6.3.5 `review` —— 监理质检员

6.3.6 `release` —— 搬家验收员

6.4 8 个专业 Agent

6.5 注意事项

7. 安全边界

8. 官方机制对齐

Related plugins

Plugins by category

hicode

Summary

Install to Claude Code

hicode Coding Agent Plugin

1. 定位

2. 目录结构

3. 安装范围

支持的安装目标

4. 使用示例

5. Moss 安装备忘

前置知识

安装命令

手动安装步骤（备用）

6. hicode Skill 速通指南

6.1 一句话定位

6.2 使用顺序

6.3 每个 Skill 详解

6.3.1 hi —— 前台接待/导航员

6.3.2 init —— 装修队（打地基、通水电）

6.3.3 scope —— 设计师（画图纸、定方案）

6.3.4 tdd —— 施工队（一砖一瓦盖房子）

6.3.5 review —— 监理质检员

6.3.6 release —— 搬家验收员

6.4 8 个专业 Agent

6.5 注意事项

7. 安全边界

8. 官方机制对齐

Related plugins

Plugins by category

6.3.1 `hi` —— 前台接待/导航员

6.3.2 `init` —— 装修队（打地基、通水电）

6.3.3 `scope` —— 设计师（画图纸、定方案）

6.3.4 `tdd` —— 施工队（一砖一瓦盖房子）

6.3.5 `review` —— 监理质检员

6.3.6 `release` —— 搬家验收员