Planweft

简体中文 | English

PlanWeft

让编程 Agent 的任务在会话结束后仍然有可读、可接续、可核验的项目记录。

PlanWeft 把任务计划、调查发现和验证结果保存到项目文件中。后续会话或协作者可以从这些记录继续工作，而不依赖旧聊天。

为什么需要 PlanWeft

Agent 的对话上下文会结束，但任务不会因此结束。PlanWeft 提供一套由项目文件承载的工作记录：Skill 指导 Agent 如何使用这些记录，Hook 在宿主支持的生命周期事件中读取状态或提供提醒，项目文件保存真正需要接续的内容。

安装

0.7.1-node.1 是 Node 迁移预发布候选；使用下列 npx 命令前请先在 npm registry 确认该版本已发布。受支持入口已改为随包 Node 脚本，并通过静态与脚本测试；保留的历史 Python/Shell 文件不是注册或指令入口。未运行 Agent 客户端本地验证。

需要 Node.js 22.13.0 或更高版本。以 Codex 完整集成为例：

npx planweft@0.7.1-node.1 add -a codex --global
npx planweft@0.7.1-node.1 doctor -a codex --global

实际使用时可显式调用 $project-docs；安装器的 doctor 只检查受管状态，不作为 Agent 客户端验证。其他宿主、scope 和 Skill-only 用法见安装指南。

一次任务怎么使用

例如，在新的 Codex 会话中：

$project-docs
修复 CSV 导入空行导致的崩溃，补回归测试，并更新受影响的使用说明。

对于需要持续规划的复杂任务，PlanWeft 会选择已有计划或在授权范围内初始化任务记录。命名计划通常位于：

your-project/
└── .planning/
    └── <date>-fix-csv-import/
        ├── task_plan.md
        ├── findings.md
        └── progress.md

模型按 Skill 指令，在用户授权范围内使用文件工具维护这些记录；后续会话或协作者可以从目标、当前阶段、调查结果、实际验证和下一步继续工作。只读请求和简单修改不要求创建新计划。

安装后 Agent 得到什么

各宿主的目录略有不同，下面是自包含插件包的简化示意：

planweft/
├── skills/
│   └── project-docs/
│       ├── SKILL.md              # 核心工作规则
│       ├── references/           # 按需读取的详细规则
│       ├── scripts/              # 计划选择、检查和交接辅助脚本
│       └── templates/            # 任务记录模板
├── hooks/                        # 宿主生命周期适配
├── extensions/ or commands/      # 宿主原生入口（如适用）
└── package metadata              # 宿主发现和版本信息

这棵树说明包的组成，不证明某台机器已经安装、信任、启用插件，也不证明模型已经读取 Skill。

Skill、Hook 和项目记录如何串起来

flowchart LR
    U[用户任务] --> A[Codex、Pi 等工具]
    A --> M[模型]
    S[project-docs Skill 指令] -. 工具提供、模型读取 .-> M
    H[生命周期 Hook] -. 事件上下文与提醒 .-> A
    M --> T[文件与测试工具]
    T --> P[task_plan.md]
    T --> F[findings.md]
    T --> G[progress.md]
    P --> N[后续会话或协作者]
    F --> N
    G --> N
    P -. 只读状态查询 .-> H

Skill 是模型读取的指令，模型决定如何在授权范围内工作并通过工具维护记录；Hook 只能在工具实际支持且启用的事件中读取状态、注入上下文或返回允许的控制结果；三份项目记录保存任务的持久状态。

关键文件的职责

文件或组件	Agent 什么时候接触	作用
skills/project-docs/SKILL.md	宿主选中 Skill 后	指导计划、调查、实施、验证和交接
references/*.md	Skill 按任务需要	提供计划选择、证据、控制和文档导航细则
scripts/cli.mjs	模型显式运行辅助命令时	Node 入口调度计划选择、初始化、检查和交接操作
scripts/planweft-launch.json	安装器创建受管 Skill 副本时	记录本机绝对 Node 路径，供 Skill 示例命令定位入口；不是可执行程序
templates/*.md	初始化或扩展记录时	提供记录结构，不代表一定会被复制
宿主 Hook 或原生扩展	会话、提示词、工具、压缩或结束事件	读取计划状态并提供上下文或提醒
task_plan.md	任务全生命周期	保存目标、阶段、下一步、阻塞和交接判断
findings.md	调查和设计阶段	保存来源、观察、假设和候选决定
progress.md	实施和验证阶段	保存实际动作、错误和 Passed / Failed / Not Run

一个任务会留下什么

复杂任务通常会在项目中留下三份记录。它们属于用户项目，不属于插件安装目录；更新或卸载 PlanWeft 不会删除它们。已有的需求、设计和复现文档仍由项目自己的目录管理。

your-project/
├── <selected task directory>/
│   ├── task_plan.md
│   ├── findings.md
│   └── progress.md
└── <existing project documents>/

Skill、Hook 和文档都不会绕过项目规则、用户授权或宿主权限。

支持的宿主

当前 npm 包包含 15 个宿主分发目标。其中 codex、claude、pi、opencode 和 dsh 是主要支持集成，其余目标目前按实验性适配处理。分发存在不等于宿主已经加载或模型已经使用；事件、原生入口和能力边界见宿主说明。

文档入口

• 安装、更新、回退与卸载
• 架构、生命周期与文件职责
• 宿主分发与能力边界

维护者资料： 开发与生成约定 · 发布与证据维护。历史计划、复现、审查和参考资料从文档导航进入。