@aipper/aiws

AIWS Core v0.3 基线的本地 filesystem CLI（产品包版本 0.1.2）。

安装

npm i -g @aipper/aiws
aiws --version

要求 Node.js >= 20（engines）。升级 / 卸载：

npm i -g @aipper/aiws@latest
npm uninstall -g @aipper/aiws

在工作区（含 .aiws/core 的目录，本仓库即一个工作区）中直接运行：

aiws status
aiws validate
aiws --help

Core 能力

• .aiws/core/ 是 Change、Task、Run、Plan、Goal 记录以及 Run events/result/evidence 的唯一机器真值；
• 记录格式固定：JSON 是每 revision 一份的状态快照，JSONL 只用于 append-only 的 run events（events.jsonl），done.signal 只是收敛标记（不是完成真值）；.aiws/changes/** 的人类可读投影用 Markdown，工作区禁止 CSV/TSV（guardrails G4）；
• Coordinator 在执行前校验父子 identity、owner/revision、context、scope、capability 和 policy；
• reconciliation 从 canonical Core artifacts 重建 Run 状态，并对损坏、冲突和不完整证据 fail closed；
• verification/review/decision/readiness 以独立 canonical record 收敛完成事实；
• Change/Task 父状态经 change advance / task advance 显式转移（--expected-revision 必填、走 Coordinator facade、转移表不可跳步）；同状态是幂等 replay（replayed:true，不写新 revision）；
• 不依赖旧 runtime、旧 CLI、旧 task ledger 或旧 workflow surface。

Adapter 暴露面

• fake-local：deterministic 本地单 Run 模拟（同步/异步）；
• pi-tmux：真实 tmux+pi 单 Run，必须提供全部显式旗标（tmux/pi 可执行文件绝对路径、cwd、scope、timeout、output limit、budget、--pi-arg、可选 --secret-env <NAME>），经 bounded worker contract 执行；仅支持异步入口，无 retry/supersede；终态执行 changed-path 审计（spawn 前基线快照 → 终态 diff → 按声明 write scope 核对），越界或审计失败强制 blocked（classification=write_scope_violation / write_scope_audit_error）——passed 含义 = 进程诚实退出且改动未越出声明 write scope；
• opencode-tmux：永久放弃（2026-10-13 决定，pi-tmux 为唯一真实执行 adapter）——代码与测试按 quarantine 原样保留，不接入 CLI、不再投资、去重重构放弃；
• local-process：quarantined（2026-10-07 决策）——已实现并有测试，但不属产品面、未接入 CLI；维持隔离，接入需单独 change；
• 未注册 adapter 以结构化 UNSUPPORTED fail closed。

Commands（18）

node packages/aiws/bin/aiws.js help
node packages/aiws/bin/aiws.js version
node packages/aiws/bin/aiws.js init      # 投影包内 skill 到 .agents/skills（--dry-run 只报告）
node packages/aiws/bin/aiws.js update    # 重新投影并 prune 本版本已移除的 managed skill
node packages/aiws/bin/aiws.js status
node packages/aiws/bin/aiws.js validate          # optional: validate . (workspace-relative path)

node packages/aiws/bin/aiws.js change --help
node packages/aiws/bin/aiws.js task --help
node packages/aiws/bin/aiws.js run --help
node packages/aiws/bin/aiws.js reconcile --help
node packages/aiws/bin/aiws.js verify --help
node packages/aiws/bin/aiws.js review --help
node packages/aiws/bin/aiws.js decision --help
node packages/aiws/bin/aiws.js readiness --help
node packages/aiws/bin/aiws.js plan --help
node packages/aiws/bin/aiws.js goal --help
node packages/aiws/bin/aiws.js context --help
node packages/aiws/bin/aiws.js memory --help

node packages/aiws/bin/aiws.js change create <id> --title <text>
node packages/aiws/bin/aiws.js task create <change-id> <id> --title <text>
node packages/aiws/bin/aiws.js change advance <change-id> --to completed --expected-revision <n>
node packages/aiws/bin/aiws.js task advance <change-id> <task-id> --to completed --expected-revision <n>
node packages/aiws/bin/aiws.js run create <change-id> <task-id> <id>
node packages/aiws/bin/aiws.js run dispatch <change-id> <task-id> <run-id> --adapter fake-local
node packages/aiws/bin/aiws.js reconcile run <change-id> <task-id> <run-id>

run dispatch --adapter pi-tmux 需要全部显式旗标（见 run --help）；缺少任一旗标返回 NEEDS_CONTEXT，不得隐式使用默认值。

旧 AIWS 0.0.96 的命令面（change start|finish|validate|sync|...、memory write|link|seed|...、goal validate-state、顶层 verify-bc/hooks/finish/...）返回结构化 LEGACY_UNSUPPORTED（exit 8），details.hint 给出迁移指向；拼错的新命令仍是 UNKNOWN_COMMAND（exit 2）。validate 接受旧式 validate . 形态，但绝对路径与 .. 逃逸仍 fail closed。legacy memory 清单仅 search/read 两个读命令被翻转为新 Core 命令（同名不同义，hint 已消歧）；write/link/seed/rebuild-index/boot/related/route 永久留 legacy。 init [path] [--dry-run] / update [path] [--dry-run] 把包内 skill bundle（skills/，三个来源：工程工作流 38 个 + 前端 taste 14 个按 pinned commit 固化 + AIWS builtin 18 个（含 ws-memory）= 70 个唯一 skill）投影到工作区 .agents/skills/（Pi ≥0.84/OpenCode 自动发现），并写 managed 快照 .agents/skills/.aiws-skills.json。init 幂等安装/刷新且不删除；update 额外 prune 本版本不再随包发布的 managed skill。两者只写 .agents/skills/**，零网络零子进程；未登记的 user-authored skill 永不被覆盖或删除。aiws skill（自定义源安装/更新/移除）仍是 legacy 命令。

memory search [<topic>] [--kind <kind>] 与 memory read <reference> 只读查询工作区 MemoryBank（.aiws/memory-bank/，非 canonical 派生上下文层），均返回带 provenance（relative path + sha256 + updated）的结构化条目。search 支持多关键词（空白分隔，AND 语义）；省略 topic 且给出 --kind 时按 kind 浏览。read 单条精读：疑似 secret 的行被替换为 [REDACTED] 并附位置列表（span 级 redact，供人取证；worker 侧 provider 仍整 payload redact）。无写命令：MemoryBank 由 git 管理的 Markdown 编辑维护，永不参与 readiness/gate。格式与安全由 npm run check:memory（在 npm run verify 链中）静态校验：路径↔kind、frontmatter 必需字段与日期、secret 形态、legacy 标注。

pi-tmux 的 worker 环境不继承父进程（契约冻结 inherit_env:false），pane 内 pi 看不到父进程的任何凭据。需要模型凭据时用 --secret-env <NAME>（可重复，≤8，必须是 secret-class 变量名）声明变量名：值在 spawn 时从父进程 process.env 解析，缺失即 blocked（classification=secret_env_missing）。值永不进入契约、参数、日志或 canonical 记录——run dispatch --adapter pi-tmux --secret-env APIROUTER_API_KEY ... 即可让 worker 拿到该凭据。

Development

npm install --ignore-scripts --no-audit --no-fund
npm run build -w packages/aiws
npm run test -w packages/aiws
npm run lint -w packages/aiws
node scripts/check-aiws-core-boundary.mjs
node scripts/check-aiws-guardrails.mjs

使用临时 workspace 运行 CLI workflow；不要读写 ../aiws-old 工作树、runtime 或旧 ledger。