easy-coding-harness 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,16 @@
 - `y`：常规功能升级
 - `z`：日常 bug 修复
 
+## 0.3.0
+
+- 补充 `repository` / `homepage` / `bugs` 包元数据，并把 README 中的 CHANGELOG 链接改为 GitLab 绝对地址，修复 npm 页面相对链接跳转到 404 的问题。
+- README 改为使用导向说明，主线调整为安装、两阶段初始化、日常 `/ec-workflow` 入口、命令表、平台差异和真实 skill 清单。
+- MEMORY_LONG 门控改由 `easy_coding_state.py transition` 机械下发 `memory_long` 指令，避免短期记忆未超过阈值时被 prompt 误触发长期沉淀。
+- ec-memory 补充短期记忆消费后的删除步骤：成功蒸馏更早条目并更新长期索引后，删除已消费短期文件，仅保留最近 `short_term_keep` 条。
+- 实施 / 审查 / 验证三阶段统一强制子代理：IMPLEMENT 删除"主代理直接实现"分支，`single` / `sequential` / `parallel` 都派子代理（仅编排形态不同——单个串行执行也起子代理），保护主代理上下文不被实现细节污染；REVIEW / VERIFICATION 口径校齐，去掉"改动集大才派子代理"等矛盾表述。
+- 新增 `easy-coding update` 命令：更新全局 CLI 到最新发布版；存量项目仍按需单独执行 `easy-coding upgrade`。
+- 存量项目需要执行 `easy-coding upgrade` 才能拿到新的 hook 与 skill 模板。
+
 ## 0.2.1
 
 - 新增 `easy_coding_state.py` 运行时状态 API，统一收口当前任务指针、任务状态、阶段流转、关闭/完成、`repo_paths` 等读写入口。

package/README.md

@@ -1,23 +1,16 @@
 # Easy Coding Harness
 
-把"AI 编码 Harness"一键安装到各 agent 平台标准目录的 CLI 脚手架。在项目里跑一次
-`easy-coding init`，按所选平台把 skills / hooks / 子代理 / 主约束文件写入平台标准目录，
-agent 原生识别——用 `/ec-`（Claude Code / Qoder）或 `$ec-`（Codex）即可调用。
+Easy Coding Harness 是一个 CLI 脚手架，用来把 Easy Coding 工作流安装到 Claude Code、Codex、Qoder 的原生目录。它只负责部署 skills、hooks、子代理、主约束文件和 `.easy-coding/` 运行时骨架，不分析项目代码；项目理解由安装后的 agent 通过 `ec-init` 完成。
 
-## 核心理念
-
-- **平台标准目录**：skills / hooks / agents 写进 `.claude/`、`.agents/` + `.codex/`、
-  `.qoder/`，复用 agent 已有的发现机制，不造新轮子。
-- **运行时 dead-drop**：`.easy-coding/` 存放 config / state / tasks / memory，所有产物
-  平台无关。换 agent、跨会话，信息零损失。
-- **约束即护城河**：8 阶段状态机 + 2 终态，WAITING_CONFIRM 与 VERIFICATION 是硬门控，
-  "没跑过的命令不算通过"。
+下文默认用 `/ec-*` 表示 Claude Code / Qoder 的触发方式；Codex 中对应使用 `$ec-*`。
 
 ## 安装
 
 ```bash
-# 方式一：源码（开发者 / 内网）
-git clone <repo> && cd easy-coding-harness && ./install.sh
+# 方式一：源码安装（开发者 / 内网）
+git clone <repo>
+cd easy-coding-harness
+./install.sh
 
 # 方式二：npm 正式环境（latest）
 npm install -g easy-coding-harness
@@ -28,89 +21,138 @@ npm install -g easy-coding-harness@beta
 easy-coding --version
 ```
 
-三种方式都注册全局命令 `easy-coding`，效果一致。
+`0.x.x` 仍按内测版本管理时，优先使用 `easy-coding-harness@beta`；正式发布后使用默认 `latest` 安装命令。
 
-当前 `0.x.x` 版本仍为内测版本时，优先使用 `beta` dist-tag；正式发布后使用默认 latest 安装命令。
+## 快速开始
 
-## 版本
+1. 在目标项目根目录安装 harness 文件：
 
-版本号严格使用 `x.y.z`：
+```bash
+easy-coding init
+```
 
-- `x`：大的功能迭代；`0.x.x` 表示内测版本
-- `y`：常规功能升级
-- `z`：日常 bug 修复
+默认安装 Claude Code 支持。需要指定平台时：
 
-完整更新日志见 [CHANGELOG.md](CHANGELOG.md)。
+```bash
+easy-coding init --agent=claude-code,codex,qoder
+```
 
-## 命令
+2. 打开目标 agent，运行项目知识初始化：
 
-| 命令 | 用途 |
-|------|------|
-| `easy-coding init` | 首次接入。`--agent=claude-code,codex,qoder` 选平台，`-y` 默认 claude-code |
-| `easy-coding add-agent` | 给已有项目追加平台支持 |
-| `easy-coding upgrade` | CLI 更新后同步项目里的功能文件（生成区覆盖，用户资产不动） |
-| `easy-coding status` | 查看已装平台、版本、当前任务状态 |
-| `easy-coding clear` | 移除 harness 安装物并保留 tasks / spec / memory / project.yaml；优先按 install manifest 精准清理，旧配置或损坏 manifest 会回退到模板兜底清理 |
+```text
+/ec-init
+```
 
-## 两阶段初始化
+`ec-init` 会让 agent 读取项目，生成 `.easy-coding/SOUL.md`、`.easy-coding/RULES.md`、`.easy-coding/ABSTRACT.md`、`.easy-coding/TEST_STRATEGY.md` 等项目知识文件。这个步骤幂等，重复运行是安全的。
 
-CLI 是纯文件搬运工，不做任何项目分析。初始化分两步：
+3. 日常开发统一从工作流入口开始：
 
-1. **CLI** `easy-coding init` —— 装文件 + 建 `project-init` 占位任务。
-2. **Agent** `/ec-init` —— agent 分析代码，生成 SOUL / RULES / ABSTRACT / TEST_STRATEGY，
-   自动判断初创 vs 迭代项目。幂等，重复跑安全。
+```text
+/ec-workflow 实现 xxx 功能
+```
+
+`ec-workflow` 会创建或恢复任务，并按阶段调度分析、实现、审查、验证和记忆归档。
+
+## 工作流
+
+```text
+INIT -> ANALYSIS -> WAITING_CONFIRM -> IMPLEMENT -> REVIEW -> VERIFICATION
+                          ^                ^                      |
+                          |                +---- repair loop -----+
+                          +--- revision ---+                      |
+                                                        [user acceptance]
+                                                                  |
+                                          MEMORY_SHORT -> MEMORY_LONG -> COMPLETE
+any stage --[user abort via ec-task-close]--> CLOSED
+```
+
+- `WAITING_CONFIRM` 是计划确认硬门控，未确认不进入实现。
+- `VERIFICATION` 是验证硬门控，未实际运行的 lint、typecheck、test 不算通过。
+- `MEMORY_SHORT` 写入本次任务短期记忆。
+- `MEMORY_LONG` 只有短期记忆数量超过阈值时才沉淀长期记忆，否则 no-op。
+
+## CLI 命令
+
+| 命令 | 用途 |
+| --- | --- |
+| `easy-coding init` | 首次接入项目，安装所选平台的 skills、hooks、agents、主约束和运行时骨架 |
+| `easy-coding add-agent` | 给已接入项目追加 Claude Code、Codex 或 Qoder 支持 |
+| `easy-coding upgrade` | CLI 升级后同步项目内生成文件，生成区覆盖，用户资产保留 |
+| `easy-coding update` | 更新全局 CLI 到最新发布版 |
+| `easy-coding status` | 查看已安装平台、harness 版本、当前任务状态 |
+| `easy-coding clear` | 移除 harness 安装物，保留 tasks、spec、memory、project.yaml 等用户资产 |
 
-之后日常工作统一走 `/ec-workflow`。
+## Skill 清单
 
-## 12 个 skill
+### 流程 skills
 
 | skill | 职责 |
-|------|------|
-| ec-init | 项目知识初始化（幂等，一次性） |
-| ec-workflow | 工作流状态机 + 任务发现/恢复（日常入口） |
-| ec-brainstorming | 实现前设计探索（硬设计门，复刻 Superpowers 方法论） |
-| ec-analysis | 需求分析 + 执行计划 + 测试策略 |
-| ec-implementing | 编码实现 + 子代理并行调度 + 任务卡 |
-| ec-reviewing | 多维度审查（accept/fix/replan/blocked） |
-| ec-verification | 验证硬闸门 + 用户验收修复循环 |
-| ec-memory | 短期滑动窗口 + 长期记忆沉淀（schema v2） |
-| ec-task-management | 任务面板（创建 / 列表） |
-| ec-task-close | 任务中断与关闭 |
-| ec-git | git 操作约束 + 跨仓库提交 |
-| ec-meta | harness 自身架构理解 + 本地定制 |
-
-## 三平台支持
-
-| | Claude Code | Codex | Qoder |
-|---|---|---|---|
-| Skills 目录 | `.claude/skills/` | `.agents/skills/` | `.qoder/skills/` |
-| 触发符 | `/` | `$` | `/` |
-| Hook 配置 | `.claude/settings.json` | `.codex/hooks.json` | `.qoder/settings.json` |
-| 主约束 | `CLAUDE.md` | `AGENTS.md` | `AGENTS.md` |
-| 中国版 | — | — | `.qodercn/` |
-
-同一份 skill 模板，平台差异通过 `{{placeholder}}` 在安装时解析。
-
-## 工作流状态机
+| --- | --- |
+| `ec-workflow` | 统一入口，负责任务创建、恢复、阶段流转和 stage skill 调度 |
+| `ec-brainstorming` | 实现前的设计探索和方案发散 |
+| `ec-analysis` | 生成 dev-spec、执行计划和测试策略 |
+| `ec-implementing` | 按确认后的计划执行代码实现 |
+| `ec-reviewing` | 多维度代码审查，输出 accept / fix / replan / blocked 结论 |
+| `ec-verification` | 执行 lint、typecheck、test 等验证硬门控，并处理验收修复循环 |
+| `ec-memory` | 写短期记忆，并在超过阈值时沉淀长期记忆 |
+| `ec-task-management` | 查看、创建、选择、恢复任务 |
+| `ec-task-close` | 用户主动中断任务并关闭 |
+| `ec-git` | 约束 git diff、commit、push、跨仓库提交等交付动作 |
+
+### 内置 skills
 
-```
-INIT → ANALYSIS → WAITING_CONFIRM → IMPLEMENT → REVIEW → VERIFICATION
-                                        ↑                     │
-                                        └──── 修复循环 ────────┘
-                                                       [用户验收]
-                                        MEMORY_SHORT → MEMORY_LONG → COMPLETE
-任何阶段 ──[用户中断]──→ CLOSED
+| skill | 职责 |
+| --- | --- |
+| `ec-init` | 项目知识初始化和升级后的知识适配 |
+| `ec-meta` | 理解 harness 自身架构、平台文件和本地定制方式 |
+
+## 平台支持
+
+| 平台 | Skills 目录 | 触发符 | Hook 配置 | 主约束 |
+| --- | --- | --- | --- | --- |
+| Claude Code | `.claude/skills/` | `/` | `.claude/settings.json` | `CLAUDE.md` |
+| Codex | `.agents/skills/` | `$` | `.codex/hooks.json` | `AGENTS.md` |
+| Qoder | `.qoder/skills/` | `/` | `.qoder/settings.json` | `AGENTS.md` |
+| Qoder 中国版 | `.qodercn/skills/` | `/` | `.qodercn/settings.json` | `AGENTS.md` |
+
+同一份 skill 模板会在安装时根据平台替换 `{{placeholder}}`，因此日常使用遵循各平台自己的触发符和目录约定。
+
+## 升级
+
+全局 CLI 更新后，已接入的项目需要在项目根目录执行：
+
+```bash
+easy-coding upgrade
 ```
 
-## 开发
+`upgrade` 会刷新生成区内的 skills、hooks、agents、主约束模板和运行时模板，不会删除已有任务、spec、memory、project.yaml 或项目知识文件。
+
+## 版本与更新日志
+
+版本号使用 `x.y.z`：
+
+- `x`：大的功能迭代；`0.x.x` 表示内测版本
+- `y`：常规功能升级
+- `z`：日常 bug 修复
+
+完整更新日志见 [CHANGELOG.md](https://gitlab.alibaba-inc.com/shixin.ysx/easy-coding-harness/-/blob/master/CHANGELOG.md)。
+
+## 开发者命令
 
 ```bash
 npm install
-npm run build      # tsup 编译 + 拷贝模板到 templates/
-npm test           # vitest
-npm run lint       # biome
+npm run build       # tsup 编译 + 拷贝 src/templates 到 templates/
+npm test            # vitest
+npm run lint        # biome check src/
+npm run typecheck   # tsc --noEmit
 ```
 
-源码结构：`src/commands/`（CLI 命令）、`src/configurators/`（平台配置器）、
-`src/templates/`（skills / hooks / 子代理 / 主约束模板）、`src/types/`（运行时数据契约）、
-`src/utils/`（文件写入 / 配置 / 分区替换等）。
+源码结构：
+
+| 目录 | 职责 |
+| --- | --- |
+| `src/commands/` | CLI 命令 |
+| `src/configurators/` | Claude Code、Codex、Qoder 平台安装器 |
+| `src/templates/` | skills、hooks、agents、主约束、运行时模板源 |
+| `src/types/` | 运行时状态和平台类型 |
+| `src/utils/` | 文件写入、配置、模板路径、gitignore、marked region 等工具 |

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import chalk7 from "chalk";
+import chalk8 from "chalk";
 import { Command } from "commander";
 
 // src/commands/add-agent.ts
@@ -1827,10 +1827,40 @@ async function status() {
   }
 }
 
-// src/commands/upgrade.ts
-import path19 from "path";
+// src/commands/update.ts
+import { execFileSync } from "child_process";
 import { cancel as cancel3, confirm as confirm3, outro as outro4 } from "@clack/prompts";
 import chalk6 from "chalk";
+async function update(opts) {
+  renderBanner();
+  const tag = opts.tag ?? "latest";
+  const spec = `${PACKAGE_NAME}@${tag}`;
+  const plan = ["update runs one step:", `  refresh the global CLI:  npm install -g ${spec}`].join(
+    "\n"
+  );
+  if (opts.dryRun) {
+    console.log(plan);
+    return;
+  }
+  if (!opts.yes) {
+    const confirmed = await confirm3({
+      message: `Update the global CLI to ${spec}?`,
+      initialValue: true
+    });
+    if (typeof confirmed === "symbol" || !confirmed) {
+      cancel3("Update cancelled.");
+      return;
+    }
+  }
+  console.log(chalk6.cyan(`\u2192 npm install -g ${spec}`));
+  execFileSync("npm", ["install", "-g", spec], { stdio: "inherit" });
+  outro4(chalk6.green("Global CLI updated."));
+}
+
+// src/commands/upgrade.ts
+import path19 from "path";
+import { cancel as cancel4, confirm as confirm4, outro as outro5 } from "@clack/prompts";
+import chalk7 from "chalk";
 async function upgrade(opts) {
   renderBanner();
   const cwd = process.cwd();
@@ -1848,7 +1878,7 @@ async function upgrade(opts) {
   }
   const relation = compareVersions(installedVersion, VERSION);
   if (relation === 0) {
-    outro4(chalk6.green(`easy-coding harness is already up to date (${VERSION}).`));
+    outro5(chalk7.green(`easy-coding harness is already up to date (${VERSION}).`));
     return;
   }
   if (relation === 1) {
@@ -1868,12 +1898,12 @@ async function upgrade(opts) {
     return;
   }
   if (!opts.yes) {
-    const shouldUpgrade = await confirm3({
+    const shouldUpgrade = await confirm4({
       message: "Apply this harness upgrade?",
       initialValue: true
     });
     if (typeof shouldUpgrade === "symbol" || !shouldUpgrade) {
-      cancel3("Upgrade cancelled.");
+      cancel4("Upgrade cancelled.");
       return;
     }
   }
@@ -1890,7 +1920,7 @@ async function upgrade(opts) {
   await ensureEasyCodingSessionsIgnored(cwd);
   await updateHarnessVersion(configPath, VERSION);
   await setPendingInitSince(cwd, VERSION);
-  outro4(chalk6.green(`easy-coding harness upgraded to ${VERSION}.`));
+  outro5(chalk7.green(`easy-coding harness upgraded to ${VERSION}.`));
 }
 
 // src/cli.ts
@@ -1899,7 +1929,7 @@ function withErrorHandling(fn) {
     try {
       await fn(opts);
     } catch (error) {
-      console.error(chalk7.red("Error:"), error instanceof Error ? error.message : error);
+      console.error(chalk8.red("Error:"), error instanceof Error ? error.message : error);
       if (process.env.EC_DEBUG && error instanceof Error) {
         console.error(error.stack);
       }
@@ -1913,6 +1943,7 @@ program.name("easy-coding").description(PACKAGE_NAME).version(VERSION, "-v, --ve
 program.command("init").description("Initialize easy-coding harness in current project").option("--agent <list>", "Comma-separated platforms: claude-code,codex,qoder").option("-y, --yes", "Skip prompts, use defaults").action(withErrorHandling(init));
 program.command("add-agent").description("Add agent platform support to an existing project").option("--agent <list>", "Comma-separated platforms to add").action(withErrorHandling(addAgent));
 program.command("upgrade").description("Upgrade harness files to current CLI version").option("--dry-run", "Preview changes without applying").option("-y, --yes", "Skip confirmation").action(withErrorHandling(upgrade));
+program.command("update").description("Refresh the global CLI to the latest published version").option("--tag <tag>", "npm dist-tag or version to install", "latest").option("--dry-run", "Preview the install command without running it").option("-y, --yes", "Skip confirmation").action(withErrorHandling(update));
 program.command("status").description("Show installed agents, version, and tasks").action(withErrorHandling(status));
 program.command("clear").description("Remove installed harness files (skills, hooks, config); keep tasks, spec, memory").option("--dry-run", "Preview what would be removed without deleting").option("-y, --yes", "Skip confirmation").action(withErrorHandling(clear));
 program.parse();