loom-pi

loom-pi 是一个基于 pi 框架（pi.dev / @earendil-works/pi-coding-agent）构建的 CLI 工具。

它通过 LLM 实现「用户需求（UR）→ 产品需求（PR）→ 测试用例（TC）」三层需求知识库的增量维护，并支持按固定迭代节奏进行可控的滚动发版。现已发布至 npm。

设计原则

• 机械步骤纯代码，智能步骤走 LLM：每个 LLM 阶段带最小工具集 + 写入守卫。
• 流程纪律代码级落地：逐条需求对齐、计划先认可、归档参考清单、核验后才导入、确认后才删草稿——全部是代码级关卡，不依赖模型自觉遵守。

目录结构

loom-pi/
├── src/                 # CLI 源码（npm 包主体）
│   ├── cli.ts           # 命令入口（commander）
│   ├── config.ts        # 知识库定位 + config.yaml 加载
│   ├── schema.ts        # Loom schema —— 规则事实源
│   ├── prompts.ts       # 各阶段共享的 system prompt 骨架
│   ├── llm.ts           # pi 封装：provider 注册、Phase 会话
│   ├── guard.ts         # 写入守卫（军规 + 阶段白名单）
│   ├── report.ts        # 结构化收尾报告
│   ├── fsops.ts         # 模板复制、归档、删除等机械操作
│   ├── interact.ts      # 人工关卡 readline 交互
│   ├── spinner.ts       # 终端 spinner 动画
│   ├── superpowers.ts   # superpowers 技能解析与加载
│   └── ops/
│       ├── create.ts    # 创建：从骨架生成新知识库工作区
│       ├── pull.ts      # 拉取：统一测试平台 → 本地基线
│       ├── ingest.ts    # 收集：原始素材 → 用户需求
│       ├── derive.ts    # 派生：UR → PR → TC
│       ├── release.ts   # 发版：归档 → 核验 → 导入
│       ├── lint.ts      # 体检：检查知识库完整性
│       └── query.ts     # 查询：自然语言检索需求
│
└── starter/             # 新项目模板，一键复制即可开始
    ├── config.yaml      # 项目级配置：LLM / 导入 / 导出 / 发版
    ├── index.md         # 目录：每页一行，人浏览 + AI 定位入口
    ├── log.md           # 流水账：每次操作追加一条
    ├── traceability.md  # 追溯矩阵：每次发版刷新
    ├── docs/            # 主干 - 归档文档
    │   ├── raw_urd/     # 原始素材
    │   ├── urd/         # 用户需求
    │   ├── prd/         # 产品需求
    │   ├── test_cases/  # 测试用例
    │   └── manual/      # 用户手册：人工维护
    ├── iterations/      # 迭代 - 暂存区
    │   └── _template/    # 迭代目录模板
    │       ├── raw_urd/     # 原始素材
    │       ├── urd/         # 用户需求草稿
    │       ├── prd/         # 产品需求草稿
    │       └── test_cases/  # 测试用例草稿
    └── scripts/
        ├── export_testcases/    # pull: 平台 → 本地（导出用例）
        └── import_testcases/    # push: 本地 → 平台（Markdown 转 Excel 并上传）

快速导航

| 我要做什么 | 看哪个文档 | |---|---| | 编译、发布 npm 包到 npmjs.com | PUBLISHING.md | | 从零搭建一个新工作区（安装 CLI、复制骨架、装 superpowers） | CREATE.md | | 日常迭代（同步基线 → 收需求 → 派生 PR / TC → 发版） | starter/README.md | | 从源码本地构建、运行、断点调试 CLI | 本地调试 |

本地调试

拿到本仓库源码后，不必发布到 npm 即可在本地构建并运行 CLI 进行调试。依赖 Node ≥ 20。

1. 安装依赖 + 构建

npm install          # 安装依赖
npm run build        # tsc 编译 src/ → dist/（产物 dist/cli.js）

修改 src/ 后需重新 npm run build；也可用 npx tsc --watch 开启监听，保存即增量编译。

2. 运行本地版本

两种方式任选其一：

# 方式一：直接跑构建产物
node dist/cli.js --help
node dist/cli.js create ./my-project

# 方式二：npm link 得到全局 loom-pi 命令，指向本地源码
npm link
loom-pi --version
loom-pi --help
npm unlink -g @rslai/loom-pi   # 调试结束后解除链接

npm link 后全局 loom-pi 直接指向本仓库 dist/cli.js，重新 npm run build 即时生效，无需再次 link。若此前用 npm install -g @rslai/loom-pi 装过正式版，link 会覆盖它；npm unlink 后可重新安装正式版。

3. 断点调试

用 Node inspector 附加调试器（VS Code / Chrome DevTools）：

node --inspect-brk dist/cli.js <命令>

TS 已构建为 ES 模块，tsconfig.json 未开启 sourceMap；如需在 .ts 源码上打断点，可临时将 tsconfig.json 的 "sourceMap" 改为 true 再构建。

日志与排查

loom 每跑一条命令都会留下完整运行记录。日志默认只落文件、不打屏（与 spinner / 流式输出解耦），所以运行时屏幕上看不到日志属正常现象——要看走下面的方式。完整说明见 LOGS.md。

落点：一次命令 = 一个运行目录 <kb>/.loom/logs/<时间戳>-<命令>/，latest 软链指向最近一次，只保留最近 20 次。每个运行目录含四份日志，分两层：

| 文件 | 层 | 内容 | |---|---|---| | app.log | 应用 | 流程日志：命令生命周期、阶段用量、守卫拒绝、人工问答、异常 | | llm.jsonl / llm.md | loom ↔ pi | 会话层：loom 发给 pi 的每轮指令 + pi 归一化后的响应（机器版 / 人读版） | | wire.jsonl / wire.md | pi ↔ 大模型 | wire 层：真正打到端点的完整请求体 + 端点返回的原始响应体（机器版 / 人读版） |

想看「业务上让模型干了什么」看 llm.*；想看「实际发出去 / 收回来的报文」看 wire.*。wire.* 里密钥已脱敏，默认开启，LOOM_WIRE=off 可关。

查看：

loom-pi logs                # 最近一次的大模型轮次记录（loom↔pi 会话层）
loom-pi logs --wire         # pi↔大模型的原始 HTTP 请求/响应
loom-pi logs --app          # 应用日志 app.log
loom-pi logs --list         # 列出全部历史运行
loom-pi logs --round <n>    # 只看某一轮
loom-pi logs -f             # 实时跟随当前运行
loom-pi --verbose <命令>    # 运行时把日志实时镜像到 stderr（同时照常落文件）

附：与自由对话 Agent 版（.claude/skills/loom-*）的关键差异

本 CLI 版与基于 Claude Code 自由对话的 Agent 版本有以下核心不同：

• 不依赖 CLAUDE.md：目录布局、ID 规则、页面模板、派生规则的事实源是 src/schema.ts，随各阶段 system prompt 注入（pi 会话以 noContextFiles 创建，不加载任何 CLAUDE.md / AGENTS.md）。知识库里的 CLAUDE.md 只服务 Claude Code 会话路径；改约定时两边要同步。
• superpowers 三关卡：官方技能定义流程 + 代码强制加载并断言。三阶段的流程本身由 obra/superpowers 的官方技能提供（brainstorming → ingest；writing-plans → derive；verification-before-completion → release），由 resolveSkill 做硬前置检查（技能缺失即阻塞，requireSuperpowers=false 才豁免并记入 log）、Phase.turnWithSkill 强制模型先 read 加载 SKILL.md 并断言其确已加载（未加载则阻塞）。代码兜底关卡叠加其上、不被替代：ingest 的逐条问答循环、derive 的计划认可关卡（认可前 prd/ 物理无写权限）、release 的只读核验（submit_verdict 不过即阻塞）。技能来源为已安装路径 loom.superpowersDir，不内置进本仓库。
• 军规是物理约束：LLM 只有 read/grep/find/ls（+ 守卫包装过的 write/edit），没有 Bash；log.md、原始素材、docs/urd、导出镜像目录的保护在工具层强制，白名单之外的写入直接拒绝。