@logicseek/hello-cc 0.1.1 → 0.1.3

package/docs/guide.zh-CN.md

@@ -1,8 +1,9 @@
 # hello-cc 用户指南
 
-这份文档保存详细使用说明，README 只保留项目入口和快速开始。
+这份文档说明安装、启动和日常使用流程。紧凑命令清单见
+[命令参考](commands.zh-CN.md)。
 
-## 安装和更新
+## 安装、更新和卸载
 
 全局安装 hello-cc：
 
@@ -13,10 +14,29 @@ npm install -g @logicseek/hello-cc
 更新已有的全局安装：
 
 ```bash
-npm install -g @logicseek/hello-cc@latest
+hcc update
 ```
 
-`hcc` 没有自更新命令。`hcc task update` 更新的是协作任务状态，不是安装包版本。
+`hcc update` 会执行 `npm install -g @logicseek/hello-cc@latest`。使用
+`hcc update --help` 可以查看更新选项。`hcc task update` 更新的是协作任务状态，不是安装包版本。
+
+移除本机 hooks 和 shims：
+
+```bash
+hcc uninstall
+```
+
+同时移除当前项目的 `.hello-cc` 数据和指导块：
+
+```bash
+hcc uninstall --purge --yes
+```
+
+移除全局 npm 包：
+
+```bash
+npm uninstall -g @logicseek/hello-cc
+```
 
 ## 默认入口
 
@@ -47,8 +67,8 @@ project: /path/to/project
 database: /path/to/project/.hello-cc/mesh.db
 runtime: /path/to/project/.hello-cc/runtime.json
 log: /path/to/project/.hello-cc/web.log
-open: http://<machine-ip>:8787/?project=%2Fpath%2Fto%2Fproject
-local: http://127.0.0.1:8787/?project=%2Fpath%2Fto%2Fproject
+open: http://<machine-ip>:8787/?token=<token>&project=%2Fpath%2Fto%2Fproject
+local: http://127.0.0.1:8787/?token=<token>&project=%2Fpath%2Fto%2Fproject
 shims: installed claude, codex
 PATH updated in ~/.bashrc; open a new terminal or source it
 stop: hcc down
@@ -123,6 +143,8 @@ Claude/Codex/普通 shell
 
 - 任务是项目事实。所有 peer 默认都能看到未 `done` 且未 `abandoned` 的任务。
 - 消息是带收件人的邮箱消息。`hcc msg inbox` 默认读取当前 peer 的未读消息，`hcc msg ack` 记录每个 peer 的已读状态。
+- 消息回复有 thread。回复某条消息时使用 `hcc msg reply --id N --body "..."`，
+  查看完整线程时使用 `hcc msg thread --id N`。
 - `ask` 和 `broadcast` 会写入持久消息；加 `--inject` 时，还会把内容实时注入到 Web runtime 已接管的终端。
 - 锁使用 SQLite 事务和 TTL，是协作式冲突避免，不是文件系统强制沙箱。
 
@@ -137,7 +159,8 @@ Claude/Codex/普通 shell
 - 未完成任务
 - 当前 peer 的未读消息
 - 活跃锁
-- 建议执行的 `hcc status`、`hcc peers`、`hcc task list`、`hcc msg inbox`、`hcc lock list`
+- 来自 `hcc state` 的机器可读下一步动作
+- 建议执行的 `hcc status`、`hcc state`、`hcc peers`、`hcc task list`、`hcc msg inbox`、`hcc lock list`
 
 因此，当你在已接入的 Claude/Codex 里问“其他会话在做什么”，模型应该基于 hello-cc 注入的最新状态回答，而不是回答“我无法知道其他会话”。
 
@@ -158,31 +181,41 @@ claude -p 'Do you see hello-cc open tasks?' --debug hooks --debug-file /tmp/hcc-
 
 debug 日志里应该出现 `Hook UserPromptSubmit ... provided additionalContext`，并包含 `hello-cc coordination` 块。
 
+`hcc state --peer <peer> [--resource PATH]` 会读取同一份协作状态，但不会执行
+确认消息、认领任务、获取锁、发送消息、创建 handoff 或标记完成这类协作动作。
+它返回现有项目数组、统一 `timeline`，以及 `automation` 对象。关键机器字段是
+`automation.next_action.argv`：agent 可以显式执行这条 hcc 命令，让协作流程留下
+可审计记录，而不是只依赖 prompt 里的自然语言规则。`automation.current_task`
+会携带当前 peer 的活动任务，让恢复后的会话继续同一个任务，直到交接、完成或阻塞。
+
 ## Web 控制台
 
-默认本机和内网访问：
+默认开启本机和内网访问，并启用 token 认证：
 
 ```bash
 hcc web
 ```
 
-需要令牌时再显式开启：
+裸 `hcc web` 会保存自动生成的 token，并在重启后复用。需要替换保存值时可显式设置：
 
 ```bash
-HCC_WEB_TOKEN='choose-a-long-token' hcc web --host 0.0.0.0 --port 8787
+HCC_WEB_TOKEN='choose-a-long-token' hcc web --port 8787
 ```
 
 同一内网机器打开：
 
 ```text
-http://<machine-ip>:8787/
+http://<machine-ip>:8787/?token=<token>
 ```
 
+使用 `hcc web --local` 可只监听 `127.0.0.1`。只有在可信本地/测试环境才使用
+`hcc web --no-token`。
+
 Web 控制台能做这些事：
 
 - 在一个端口里切换多个已注册项目 root
 - 直接在浏览器里注册新的项目路径
-- 查看项目状态：peers、tasks、messages、locks、handoffs、events
+- 查看项目状态：下一步动作、timeline、peers、tasks、locks
 - 操作本地终端：启动 Claude/Codex/shell、发送键盘输入、查看输出、停止接管
 
 Web 操作的是 hello-cc 管理的本机 tmux 终端：
@@ -193,63 +226,12 @@ Web 操作的是 hello-cc 管理的本机 tmux 终端：
 - 通过 `hcc peer attach` 接入的已有 tmux pane
 
 已经打开的普通 raw 终端不能被无条件捕获或控制，除非它原本就在 tmux、screen 或 hello-cc shim 之下。它仍然可以通过 hooks 和 `hcc` 命令参与任务、消息和锁。
+对于这类 coordination-only peer，Web 会通过 Timeline 展示协作轨迹，而不是显示终端流。
 
-## 常用命令
+## 命令参考
 
-```text
-# 默认入口
-hcc web [--host HOST] [--port N] [--token TEXT] [--local] [--no-discover] [--no-guidance]
-hcc down
-
-# 本地协调，无 Web
-hcc up [--no-discover] [--no-guidance]
-
-# 对等节点和状态
-hcc peers
-hcc status [--peer ID]
-hcc scan [--register]
-hcc prompt --peer ID [--kind codex|claude|shell|other] [--role ROLE]
-hcc join --peer ID [--kind codex|claude|shell|other] [--role ROLE]
-hcc env --peer ID
-hcc heartbeat [--peer ID] [--renew-locks --ttl 900]
-hcc run --peer ID --kind codex|claude|shell --role ROLE -- COMMAND [ARGS...]
-
-# Web 可控终端
-hcc peer list
-hcc peer start PEER [--kind K] [--role R] [--cwd DIR] [--restart-env] -- COMMAND [ARGS...]
-hcc peer start PEER --kind codex --resume SESSION_ID [--restart-env]
-hcc peer start PEER --kind codex --last
-hcc peer start PEER --kind claude --resume SESSION_ID [--restart-env]
-hcc peer start PEER --kind claude --continue
-hcc peer attach PEER [--pane PANE] [--kind K] [--role R] [--cwd DIR]
-hcc peer stop PEER
-hcc inject PEER TEXT [--no-enter]
-
-# 消息
-hcc msg send [--from ID] [--to ID|all] --body TEXT [--task N] [--kind note|task|handoff]
-hcc msg inbox [--peer ID] [--wait SEC] [--all] [--limit N]
-hcc msg ack [--peer ID] --id N
-hcc ask PEER MESSAGE [--from ID] [--task N] [--inject]
-hcc broadcast MESSAGE [--from ID] [--task N] [--inject]
-
-# 任务
-hcc task create --title TEXT [--body TEXT] [--from ID] [--to ID] [--priority N]
-hcc task list [--status S] [--peer ID] [--all]
-hcc task claim [--peer ID] --id N
-hcc task next [--peer ID]
-hcc task update [--peer ID] --id N --status running|review|blocked|done|abandoned [--summary TEXT] [--body TEXT] [--to ID]
-hcc task done [--peer ID] --id N --summary TEXT
-
-# 锁和交接
-hcc lock acquire [--peer ID] --resource PATH [--task N] [--ttl SEC] [--reason TEXT]
-hcc lock renew [--peer ID] --resource PATH [--ttl SEC]
-hcc lock release [--peer ID] --resource PATH [--force]
-hcc lock list [--all]
-hcc handoff create [--from ID] --summary TEXT [--task N] [--to ID] [--changed-files JSON_OR_CSV] [--tests TEXT] [--risks TEXT]
-hcc handoff list [--task N] [--limit N]
-hcc event tail [--limit N]
-hcc gc [--older-than DAYS] [--yes]
-```
+使用 `hcc --help` 查看命令列表，使用 `hcc <command> --help` 查看单个命令。
+维护中的命令摘要见 [命令参考](commands.zh-CN.md)。
 
 ## 稳定 peer 身份
 
@@ -284,10 +266,34 @@ hcc task next
 hcc lock acquire --resource vllm/router --ttl 900 --reason "实现路由诊断"
 ```
 
+`task next` 会先返回当前 peer 已经认领、运行、审查或阻塞中的任务。只有明确
+要再接一个 pending 任务时，才使用 `hcc task next --force`。
+
+当工作确实可以并行时，用显式团队把父任务拆成子任务：
+
+```bash
+hcc team plan --from-task 12 \
+  --item "docs:更新用户指南" \
+  --item "tests:增加回归测试" \
+  --workers codex:1,claude:1
+
+hcc team start --from-task 12 \
+  --item "docs:更新用户指南" \
+  --item "tests:增加回归测试" \
+  --workers codex:1,claude:1
+
+hcc team status --task 12
+```
+
+`team plan` 是只读命令。`team start` 会创建子任务和分配消息，但不会隐藏地启动
+模型进程。每个 agent 仍然通过普通任务、锁、交接和完成命令处理自己的子任务。
+
 发消息或实时注入：
 
 ```bash
 hcc msg send --to claude-a --body "实现已准备好供审查。"
+hcc msg reply --id 12 --body "已审查，未发现阻塞问题。"
+hcc msg thread --id 12
 hcc ask claude-a "请审查当前实现。" --inject
 hcc broadcast "暂停编辑 vllm/router，等待任务完成。" --inject
 ```
@@ -311,7 +317,7 @@ hcc lock release --resource vllm/router
 | `HCC_PEER` | 默认 peer 身份 |
 | `HCC_ROOT` | 覆盖项目根目录 |
 | `HCC_DB` | 覆盖数据库路径 |
-| `HCC_WEB_TOKEN` | 可选 Web 访问令牌 |
+| `HCC_WEB_TOKEN` | 替换并保存固定 Web 访问令牌 |
 | `HCC_RUNTIME_URL` | 直接指定 runtime URL |
 | `HCC_NO_AUTO_INSTALL_TMUX=1` | 禁用 tmux 自动安装，主要用于测试 |
 

package/docs/implementation.md

@@ -119,7 +119,9 @@ Messages:
 ```text
 from peer
 to peer | all | tag:<tag> | task:<task-id>
-kind note | ask | handoff | system
+kind note | ask | reply | handoff | system
+reply_to optional source message id
+thread_id root message id for threaded collaboration history
 delivery store-only | inject-terminal | both
 ```
 
@@ -128,11 +130,29 @@ Tasks:
 ```text
 pending -> claimed -> running -> review/block/done|abandoned
 owner is dynamic; there is no fixed dispatcher
+parent_id/team_role record explicit team child tasks
 ```
 
 Default task reads are lifecycle-based: all peers see tasks until they are
 `done` or `abandoned`. Read/ack state exists only for messages.
 
+`hcc team plan` is read-only. `hcc team start` creates child tasks under the
+parent and assignment messages; it does not spawn hidden agents or bypass the
+normal claim/lock/handoff protocol.
+
+State:
+
+```text
+hcc state / /api/state
+timeline derived from messages, handoffs, tasks, locks, and selected events
+automation.next_action.argv suggests the next explicit hcc command
+automation.current_task preserves sticky task context across prompts
+```
+
+State inspection does not perform coordination actions such as acking messages,
+claiming tasks, acquiring locks, sending messages, creating handoffs, or marking
+tasks done. Opening a DB may still run schema/version maintenance.
+
 Locks:
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logicseek/hello-cc",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Local control plane for coordinating Claude Code, Codex, and other coding CLI sessions.",
   "type": "module",
   "bin": {
@@ -11,8 +11,10 @@
     "bin/",
     "lib/",
     "scripts/",
+    "assets/",
     "README.md",
     "README.zh-CN.md",
+    "CHANGELOG.md",
     "LICENSE",
     "docs/"
   ],
@@ -20,6 +22,10 @@
     "node": ">=24.0.0"
   },
   "scripts": {
+    "release:notes": "node ./scripts/release-notes.mjs",
+    "release:check": "node ./scripts/release-notes.mjs --check",
+    "release:github": "node ./scripts/github-release.mjs",
+    "release:github:dry-run": "node ./scripts/github-release.mjs --dry-run",
     "smoke": "node ./bin/hcc.mjs --help",
     "test": "node ./scripts/regression.mjs",
     "test:regression": "node ./scripts/regression.mjs"

package/scripts/github-release.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+const repoRoot = path.resolve(import.meta.dirname, '..');
+const githubApi = 'https://api.github.com';
+
+function usage() {
+  console.log(`github-release
+
+Usage:
+  node scripts/github-release.mjs [--version VERSION] [--repo OWNER/REPO] [--dry-run]
+
+Creates or updates the GitHub Release for vVERSION using the matching
+CHANGELOG.md section as the release body.
+
+Authentication:
+  Set GH_TOKEN or GITHUB_TOKEN to a token with repo release permissions.
+`);
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function parseArgs(argv) {
+  const opts = { dryRun: false, help: false, repo: null, version: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else if (arg === '--dry-run') {
+      opts.dryRun = true;
+    } else if (arg === '--repo') {
+      opts.repo = argv[++i];
+      if (opts.repo === undefined) throw new Error('Missing value for --repo');
+    } else if (arg.startsWith('--repo=')) {
+      opts.repo = arg.slice('--repo='.length);
+    } else if (arg === '--version') {
+      opts.version = argv[++i];
+      if (opts.version === undefined) throw new Error('Missing value for --version');
+    } else if (arg.startsWith('--version=')) {
+      opts.version = arg.slice('--version='.length);
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return opts;
+}
+
+function normalizeVersion(version) {
+  return String(version || '').replace(/^v/, '');
+}
+
+function releaseSection(markdown, version) {
+  const lines = markdown.split(/\r?\n/);
+  const heading = `## ${version}`;
+  const start = lines.findIndex((line) => line.trim() === heading);
+  if (start < 0) return null;
+
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^##\s+/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join('\n').trimEnd();
+}
+
+function validateSection(section, version) {
+  const problems = [];
+  if (!section) {
+    problems.push(`CHANGELOG.md is missing section ## ${version}`);
+    return problems;
+  }
+  if (!section.includes('### Summary')) problems.push(`## ${version} is missing ### Summary`);
+  if (!section.includes('### Highlights')) problems.push(`## ${version} is missing ### Highlights`);
+  if (section.includes('TODO') || section.includes('TBD')) problems.push(`## ${version} still contains TODO/TBD text`);
+  const bulletCount = (section.match(/^- /gm) || []).length;
+  if (bulletCount < 2) problems.push(`## ${version} should include at least two release-note bullets`);
+  return problems;
+}
+
+function repoFromPackage(pkg) {
+  const repo = typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url;
+  if (!repo) return null;
+  const match = repo.match(/github\.com[:/](.+?\/.+?)(?:\.git)?$/);
+  return match ? match[1] : null;
+}
+
+function envToken() {
+  return process.env.GH_TOKEN || process.env.GITHUB_TOKEN || '';
+}
+
+async function githubRequest(method, route, token, body = null) {
+  const response = await fetch(`${githubApi}${route}`, {
+    method,
+    headers: {
+      Accept: 'application/vnd.github+json',
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+      'User-Agent': 'hello-cc-release-script'
+    },
+    body: body ? JSON.stringify(body) : undefined
+  });
+  const text = await response.text();
+  const data = text ? JSON.parse(text) : null;
+  if (!response.ok) {
+    const detail = data?.message ? `: ${data.message}` : '';
+    const error = new Error(`GitHub API ${method} ${route} failed with ${response.status}${detail}`);
+    error.status = response.status;
+    throw error;
+  }
+  return data;
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    usage();
+    return;
+  }
+
+  const pkg = readJson(path.join(repoRoot, 'package.json'));
+  const version = normalizeVersion(opts.version || pkg.version);
+  const tag = `v${version}`;
+  const repo = opts.repo || process.env.GITHUB_REPOSITORY || repoFromPackage(pkg);
+  if (!repo) throw new Error('Missing repository; pass --repo OWNER/REPO');
+
+  const changelog = fs.readFileSync(path.join(repoRoot, 'CHANGELOG.md'), 'utf8');
+  const body = releaseSection(changelog, version);
+  const problems = validateSection(body, version);
+  if (problems.length) {
+    console.error(problems.join('\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const payload = {
+    tag_name: tag,
+    name: tag,
+    body,
+    draft: false,
+    prerelease: false
+  };
+
+  if (opts.dryRun) {
+    console.log(JSON.stringify({
+      ok: true,
+      dry_run: true,
+      repo,
+      tag,
+      name: payload.name,
+      body_length: body.length,
+      body_preview: body.split(/\r?\n/).slice(0, 8).join('\n')
+    }, null, 2));
+    return;
+  }
+
+  const token = envToken();
+  if (!token) throw new Error('Missing GH_TOKEN or GITHUB_TOKEN');
+
+  let existing = null;
+  try {
+    existing = await githubRequest('GET', `/repos/${repo}/releases/tags/${tag}`, token);
+  } catch (err) {
+    if (err.status !== 404) throw err;
+  }
+
+  const result = existing
+    ? await githubRequest('PATCH', `/repos/${repo}/releases/${existing.id}`, token, payload)
+    : await githubRequest('POST', `/repos/${repo}/releases`, token, payload);
+
+  console.log(JSON.stringify({
+    ok: true,
+    action: existing ? 'updated' : 'created',
+    repo,
+    tag,
+    url: result.html_url,
+    body_length: body.length
+  }, null, 2));
+}
+
+main().catch((err) => {
+  console.error(err.message || String(err));
+  process.exitCode = 1;
+});