@wbline/pi-plan-build 0.0.0-stage → 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,151 @@
1
+ /** plan_step_control + plan_step_complete:分步执行控制(AI 完成当前步用 plan_step_complete)。 */
2
+ import fs from "node:fs";
3
+ import { StringEnum } from "@earendil-works/pi-ai";
4
+ import type {
5
+ ExtensionAPI,
6
+ ExtensionToolContext,
7
+ } from "@earendil-works/pi-coding-agent";
8
+ import { Type } from "typebox";
9
+ import { reviseStepInMarkdown } from "../core/steps.ts";
10
+ import type { PlanEngine } from "../engine.ts";
11
+
12
+ const ControlParams = Type.Object({
13
+ action: StringEnum([
14
+ "start",
15
+ "acknowledge",
16
+ "skip",
17
+ "revise",
18
+ "pause",
19
+ "resume",
20
+ "cancel",
21
+ ]),
22
+ /** acknowledge: 步骤摘要;revise: 新文本;cancel 不需要参数。 */
23
+ summary: Type.Optional(
24
+ Type.String({ description: "acknowledge 的完成摘要" }),
25
+ ),
26
+ step: Type.Optional(
27
+ Type.Integer({
28
+ minimum: 1,
29
+ description: "revise 的步骤号(默认当前就绪步)",
30
+ }),
31
+ ),
32
+ text: Type.Optional(Type.String({ description: "revise 的新步骤文本" })),
33
+ });
34
+
35
+ const CompleteParams = Type.Object({
36
+ summary: Type.String({ description: "本步实现与验证的简明摘要" }),
37
+ });
38
+
39
+ export function registerPlanStepTools(
40
+ pi: ExtensionAPI,
41
+ engine: PlanEngine,
42
+ ): void {
43
+ pi.registerTool({
44
+ name: "plan_step_control",
45
+ label: "Plan Step Control",
46
+ description:
47
+ "分步执行控制:start 批准并开始就绪步;acknowledge 指认用户声明的已完成步(记录既有事实,不授权新工作,AI 自己完成当前步用 plan_step_complete);skip 跳过;revise 修订未完成步文本;pause/resume 暂停恢复;cancel 取消分步执行(计划保留)。一次一个转移。",
48
+ parameters: ControlParams,
49
+ async execute(_id, params, _signal, _onUpdate, ctx: ExtensionToolContext) {
50
+ switch (params.action) {
51
+ case "start": {
52
+ const r = engine.tryApply({ t: "exec.step.start" }, ctx);
53
+ if ("error" in r) return err(r.error);
54
+ const st = r.state.execution?.steps.find(
55
+ (x) => x.status === "active",
56
+ );
57
+ if (!st) return err("没有进行中的步骤。");
58
+ const total = r.state.execution?.steps.length ?? 0;
59
+ return ok(
60
+ `第 ${st.n}/${total} 步已开始:${st.text}\n只实现本步,完成后调用 plan_step_complete。`,
61
+ );
62
+ }
63
+ case "acknowledge": {
64
+ const r = engine.tryApply(
65
+ { t: "exec.step.complete", summary: params.summary },
66
+ ctx,
67
+ );
68
+ if ("error" in r) return err(r.error);
69
+ return ok(r.note ?? "步骤已记录完成。");
70
+ }
71
+ case "skip": {
72
+ const r = engine.tryApply({ t: "exec.step.skip" }, ctx);
73
+ if ("error" in r) return err(r.error);
74
+ return ok(r.note ?? "步骤已跳过。");
75
+ }
76
+ case "revise": {
77
+ const s = engine.state;
78
+ const execution = s.execution;
79
+ if (!execution) return err("未处于分步执行。");
80
+ const n =
81
+ params.step ?? execution.steps.find((x) => x.status === "ready")?.n;
82
+ if (!n || !params.text)
83
+ return err("revise 需要 step(步骤号)和 text(新文本)。");
84
+ const st = execution.steps.find((x) => x.n === n);
85
+ if (!st) return err(`不存在第 ${n} 步。`);
86
+ // 同步修订计划文件中的步骤文本(受保护文件的扩展自身修订,绕过守卫:直接写)
87
+ const planPath = s.plan?.path;
88
+ if (planPath && fs.existsSync(planPath)) {
89
+ const md = fs.readFileSync(planPath, "utf8");
90
+ const revised = reviseStepInMarkdown(md, n, params.text);
91
+ if (revised !== null) fs.writeFileSync(planPath, revised);
92
+ }
93
+ const r = engine.tryApply(
94
+ { t: "exec.step.revise", n, text: params.text },
95
+ ctx,
96
+ );
97
+ if ("error" in r) return err(r.error);
98
+ return ok(`第 ${n} 步已修订:${params.text}`);
99
+ }
100
+ case "pause": {
101
+ const r = engine.tryApply({ t: "exec.pause" }, ctx);
102
+ return "error" in r ? err(r.error) : ok(r.note ?? "已暂停。");
103
+ }
104
+ case "resume": {
105
+ const r = engine.tryApply({ t: "exec.resume" }, ctx);
106
+ return "error" in r ? err(r.error) : ok(r.note ?? "已恢复。");
107
+ }
108
+ case "cancel": {
109
+ const r = engine.tryApply({ t: "exec.cancel" }, ctx);
110
+ return "error" in r ? err(r.error) : ok(r.note ?? "分步执行已取消。");
111
+ }
112
+ default:
113
+ return err(`未知 action:${String(params.action)}`);
114
+ }
115
+ },
116
+ });
117
+
118
+ pi.registerTool({
119
+ name: "plan_step_complete",
120
+ label: "Plan Step Complete",
121
+ description:
122
+ "完成当前进行中的分步(仅在本步实现与适用检查完成后调用)。摘要必填。完成立即生效,不等待用户验收;绝不开始下一步。",
123
+ parameters: CompleteParams,
124
+ async execute(_id, params, _signal, _onUpdate, ctx: ExtensionToolContext) {
125
+ const r = engine.tryApply(
126
+ { t: "exec.step.complete", summary: params.summary },
127
+ ctx,
128
+ );
129
+ if ("error" in r) return err(r.error);
130
+ if (!r.state.plan) {
131
+ return ok(`全部步骤完成,计划已收尾。\n${r.note ?? ""}`);
132
+ }
133
+ const next = r.state.execution?.steps.find((x) => x.status === "ready");
134
+ if (!next) return ok(`${r.note ?? "步骤完成。"}`);
135
+ return ok(
136
+ `${r.note ?? "步骤完成。"}\n等待用户明确批准后(plan_step_control start),再开始第 ${next.n} 步:${next.text}`,
137
+ );
138
+ },
139
+ });
140
+ }
141
+
142
+ function ok(t: string) {
143
+ return { content: [{ type: "text" as const, text: t }], details: undefined };
144
+ }
145
+ function err(t: string) {
146
+ return {
147
+ content: [{ type: "text" as const, text: t }],
148
+ details: undefined,
149
+ isError: true as const,
150
+ };
151
+ }
@@ -0,0 +1,168 @@
1
+ /** plan_task:任务生命周期元数据(new/title/include/exclude/abandon/list/show)。 */
2
+
3
+ import { StringEnum } from "@earendil-works/pi-ai";
4
+ import type {
5
+ ExtensionAPI,
6
+ ExtensionToolContext,
7
+ } from "@earendil-works/pi-coding-agent";
8
+ import { Type } from "typebox";
9
+ import { statusLine } from "../core/state.ts";
10
+ import type { PlanEngine } from "../engine.ts";
11
+ import { nextPlanPath } from "../engine.ts";
12
+
13
+ const Params = Type.Object({
14
+ action: StringEnum([
15
+ "new",
16
+ "update",
17
+ "include",
18
+ "exclude",
19
+ "abandon",
20
+ "list",
21
+ "show",
22
+ ]),
23
+ /** new: 标题(动作+对象);update: 新标题;abandon: 原因。 */
24
+ title: Type.Optional(
25
+ Type.String({ description: "new/update 的标题,或 abandon 的原因" }),
26
+ ),
27
+ /** include: 追加范围全文;exclude: 排除话题。 */
28
+ scope: Type.Optional(
29
+ Type.String({ description: "include 的完整合并范围,或 exclude 的话题" }),
30
+ ),
31
+ /** 乐观并发:必须传最近一次调用返回的 seq。 */
32
+ expectedAttached: Type.Optional(
33
+ Type.Union([Type.Integer(), Type.Null()], {
34
+ description: "当前计划 seq;new 传 null",
35
+ }),
36
+ ),
37
+ });
38
+
39
+ export function registerPlanTask(pi: ExtensionAPI, engine: PlanEngine): void {
40
+ pi.registerTool({
41
+ name: "plan_task",
42
+ label: "Plan Task",
43
+ description:
44
+ "计划任务生命周期:new 建计划(Plan 模式);update 改名;include 追加用户批准的范围;exclude 记录排除话题;abandon 显式放弃(须用户指示);list/show 查看状态。转移必须先于依赖它的写入/命令单独完成。",
45
+ parameters: Params,
46
+ async execute(_id, params, _signal, _onUpdate, ctx: ExtensionToolContext) {
47
+ const s = engine.state;
48
+
49
+ if (params.action === "list") {
50
+ return text(
51
+ s.plan
52
+ ? `当前计划:${statusLine(s)}\nseq=${s.plan.seq}`
53
+ : "当前没有计划。",
54
+ );
55
+ }
56
+ if (params.action === "show") {
57
+ if (!s.plan) return text("当前没有计划。");
58
+ const body = [
59
+ `标题:${s.plan.title}`,
60
+ `seq:${s.plan.seq}`,
61
+ `文件:${s.plan.path}${s.plan.saved ? "" : "(未写盘)"}`,
62
+ `模式:${s.mode}`,
63
+ s.plan.outcome ? `结局:${s.plan.outcome.kind}` : "结局:进行中",
64
+ "",
65
+ "## 范围",
66
+ s.plan.scope,
67
+ ].join("\n");
68
+ return text(body);
69
+ }
70
+
71
+ // 并发守卫:除 list/show 外都要匹配 expectedAttached
72
+ const expected = params.expectedAttached;
73
+ if (params.action === "new") {
74
+ if (expected !== null && expected !== undefined) {
75
+ return err("plan_task new 需要 expectedAttached: null。");
76
+ }
77
+ if (!params.title)
78
+ return err("new 需要 title(动作+对象式单一标题)。");
79
+ if (!params.scope) return err("new 需要 scope(详细范围)。");
80
+ const p = nextPlanPath(ctx.cwd, params.title);
81
+ const r = engine.tryApply(
82
+ {
83
+ t: "plan.create",
84
+ title: params.title,
85
+ scope: params.scope,
86
+ path: p,
87
+ },
88
+ ctx,
89
+ );
90
+ if ("error" in r) return err(r.error);
91
+ return text(
92
+ `计划已创建(seq=1)。canonical 路径:${p}\n请完成只读调研后把完整计划写入该文件,然后调用 plan_exit。`,
93
+ );
94
+ }
95
+
96
+ if (!s.plan) return err("当前没有计划。先 plan_task new。");
97
+ if (expected !== undefined && expected !== s.plan.seq) {
98
+ return err(
99
+ `expectedAttached=${expected} 已过期,当前 seq=${s.plan.seq}。请重读 plan_task show 后重试,不要盲目换目标。`,
100
+ );
101
+ }
102
+
103
+ switch (params.action) {
104
+ case "update": {
105
+ if (!params.title) return err("update 需要 title。");
106
+ const r = engine.tryApply(
107
+ { t: "plan.title", title: params.title },
108
+ ctx,
109
+ );
110
+ return "error" in r
111
+ ? err(r.error)
112
+ : text(`标题已更新:${r.state.plan?.title ?? ""}`);
113
+ }
114
+ case "include": {
115
+ if (!params.scope)
116
+ return err(
117
+ "include 需要 scope(用户批准的追加内容,完整合并范围)。",
118
+ );
119
+ const r = engine.tryApply(
120
+ { t: "plan.scope.append", addition: params.scope },
121
+ ctx,
122
+ );
123
+ return "error" in r
124
+ ? err(r.error)
125
+ : text(
126
+ `范围已追加(seq=${r.state.plan?.seq ?? 1})。请相应更新计划文件;若文件已审阅过,需重新 plan_exit。`,
127
+ );
128
+ }
129
+ case "exclude": {
130
+ if (!params.scope) return err("exclude 需要 scope(排除的话题)。");
131
+ const r = engine.tryApply(
132
+ { t: "plan.exclude", topic: params.scope },
133
+ ctx,
134
+ );
135
+ return "error" in r
136
+ ? err(r.error)
137
+ : text(`已记录排除话题:${params.scope}`);
138
+ }
139
+ case "abandon": {
140
+ if (!params.title)
141
+ return err(
142
+ "abandon 需要原因(放在 title 参数)。仅限用户明确指示后调用。",
143
+ );
144
+ const r = engine.tryApply(
145
+ { t: "plan.abandon", reason: params.title },
146
+ ctx,
147
+ );
148
+ return "error" in r
149
+ ? err(r.error)
150
+ : text(`计划已放弃。文件保留:${s.plan.path}`);
151
+ }
152
+ default:
153
+ return err("未知 action。");
154
+ }
155
+ },
156
+ });
157
+ }
158
+
159
+ function text(t: string) {
160
+ return { content: [{ type: "text" as const, text: t }], details: undefined };
161
+ }
162
+ function err(t: string) {
163
+ return {
164
+ content: [{ type: "text" as const, text: t }],
165
+ details: undefined,
166
+ isError: true as const,
167
+ };
168
+ }