# loom-pi

**Repository Path**: rslai/loom-pi

## Basic Information

- **Project Name**: loom-pi
- **Description**: P.I. 实现的 loom 版本
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-05
- **Last Updated**: 2026-07-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# loom-pi

`loom-pi` 是一个基于 **pi 框架**（[pi.dev](https://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 技能解析与加载
│   ├── logger.ts        # 轻量分级日志：默认只落文件、与 UI 解耦
│   ├── fmtargs.ts       # 工具调用参数压成一行人读摘要（屏幕/存档共用）
│   ├── pytool.ts        # 统一 Python 脚本调用入口（在 kb 根运行）
│   ├── tstool.ts        # 统一 TS 脚本调用入口（运行时转译 + 进程内调用）
│   ├── raw2md.ts        # ingest 前置：非 md 原始素材 → md（markitdown）
│   ├── record/          # 运行记录存档
│   │   ├── llm.ts       # loom↔pi 会话层：每轮 turn 全量存档（llm.jsonl / llm.md）
│   │   └── wire.ts      # pi↔大模型 wire 层：原始 HTTP 请求/响应（wire.jsonl / wire.md）
│   └── ops/
│       ├── create.ts       # 创建：从骨架生成新知识库工作区
│       ├── pull.ts         # 拉取：统一测试平台 → 本地基线
│       ├── ingest.ts       # 收集：原始素材 → 用户需求
│       ├── derive.ts       # 派生：UR → PR → TC
│       ├── carryimages.ts  # 派生后置：确定性地把图片附件带进新 TC 草稿
│       ├── release.ts      # 发版：归档 → 核验 → 导入
│       ├── lint.ts         # 体检：检查知识库完整性
│       ├── query.ts        # 查询：自然语言检索需求
│       └── logs.ts         # 查看运行记录（会话层 / wire 层 / 应用日志）
│
└── 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](PUBLISHING.md) |
| 从零搭建一个新工作区（安装 CLI、复制骨架、装 superpowers） | [CREATE.md](CREATE.md) |
| 日常迭代（同步基线 → 收需求 → 派生 PR / TC → 发版） | [starter/README.md](starter/README.md) |
| 从源码本地构建、运行、断点调试 CLI | [本地调试](#本地调试) |

---

## 本地调试

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

### 1. 安装依赖 + 构建

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

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

### 2. 运行本地版本

两种方式任选其一：

```bash
# 方式一：直接跑构建产物
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）：

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

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

---

## 日志与排查

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

**查看**：

```bash
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、导出镜像目录的保护在工具层强制，白名单之外的写入直接拒绝。

---