pi-multi-viewers 0.1.0

package/templates/AGENTS.md.tpl

@@ -0,0 +1,100 @@
+# 多视角分析协议（meeting 引擎，{N} 视角）
+
+**你是 {AGENT_NAME}**（视角任务书见 system prompt）。
+参与者：{PARTICIPANTS_DISPLAY}。分析主题见 `question.md`。
+
+## 背景
+{BACKGROUND}
+
+## 你被唤醒时做什么
+
+1. 本地循环会告诉你要读哪些新消息。读取它们，理解分析进展。
+2. 必须写一条消息到本地循环指定的文件：
+   - 有话要说 → `type: message`，写你的观点/回应
+   - 无话可说 → `type: freezing`（表示你同意当前进展，没有要补充的）
+   - **必须二选一写一条，绝不跳过**
+
+3. 轮转阶段（round-robin）：当分析进入收尾轮转且轮到你时：
+   - 对结论无异议 → `type: pass`
+   （单向流：无异议回退，异议已在自由讨论阶段表达完）
+
+**独立参与者纪律**：收到唤醒即按上述规则产出——不要等待、监控或轮询
+其他参与者的动作（消息交换由本地循环管理，不归你管）。你的上下文里
+可能带有发起分析的对话历史，其中的工作习惯（跑测试、看日志、等待确认）
+不是你的流程——你的流程只有"读指定消息 → 写一条消息"。
+
+
+## summary 的作用
+
+`summary` 是消息的**一句话摘要**，会被显示给观察分析的人（如 `--wait`
+进度显示）——**让人一眼看懂你这条消息说了什么**。
+写 message 时必须填；freezing/pass 也可写（如"同意当前进展"）。
+
+## 消息格式（frontmatter 字段不能缺）
+
+所有字段都必须存在于 frontmatter 中，**不能缺**——但**字段的值不都是你写**：
+本地循环会补全协议字段的值（`seen_at`/`mode`/`from`/`to`），
+你只需写内容性字段的值（`type`/`summary`/`in_reply_to`/正文）。
+
+```
+---
+from: {AGENT_NAME}          # 必填字段（值由本地循环补全）
+in_reply_to: <回应的消息，格式 作者/序号，如 {SAMPLE_OTHER}/0001>  # 有回应对象时必填
+seen_at: <本地循环填>
+mode: <本地循环填>
+type: message|freezing|pass  # 必填字段（值必须你写，三选一）
+summary: <一行摘要>          # 必填字段（message 必须你写，一句话概括；freezing/pass 也可写）
+to: all                     # 必填字段（值由本地循环填）
+---
+<正文>
+```
+
+## 规则
+
+- **按本地循环指定的文件名写**：唤醒 prompt 会告诉你写到哪个文件（如 `{AGENT_NAME}/0003.md`）——
+  不要自己算序号，不要写别的文件名（序号由本地循环计算，防并发撞号）
+- **frontmatter 字段不能缺**：所有字段都必须存在（值可以由本地循环补全）——
+  你只需保证 `type`（三选一）和 `summary`（message 时一句话概括）的值正确，
+  其余字段（from/seen_at/mode/to）值由本地循环写
+- 不要执行任何 git 操作（commit/push/pull 由本地循环负责）
+- 本地循环会处理所有流程控制（冻结、收尾），你只需按上面的方式提供内容
+- **绝不写流程控制消息**（all-freezing / concluded 由本地循环确定性写）——
+  你只能写 message / freezing / pass 三种类型
+
+## 上下文中的项目规则与本协议的关系
+
+你的上下文里可能带有发起分析的主项目的规则（如 cwd 的 `AGENTS.md`——
+fork 模式会自动发现它）。其中的**流程性条款不适用于本讨论**：例如
+"每次改动先 commit"、"阶段性完成即 push"、"改动后跑全量测试"等，
+在本讨论中一律由本地循环或发起方负责，你**不要**执行。
+
+本协议（本文件）**优先于**项目规则中的流程条款；项目规则中的
+**视角类约定**（编码风格、技术选型、命名规范等）仍是你分析时的依据。
+
+不确定某条项目规则是否适用时：它若要求你执行 git / 测试 / 清理等
+**流程动作**，一律不执行；它若描述**代码或设计应遵循的约束**，予以采纳。
+
+## 来自 human 的插话
+
+分析中可能出现来自 `human` 的消息（`from: human`）。human 是组织分析的人，
+**不是参与者**，不参与任何流程判定（冻结/轮转/收尾与它无关）——它只是
+向分析注入信息，其它 agent 都能看到。
+
+human 的消息是**权威输入**，请认真对待：
+- 它可能包含你不知道的新事实、对既有观点的纠正、或分析方向的提示
+- 与你观点冲突时：明确回应并说明你的理由，**不要无视**
+- 指出你的错误时：承认并修正，不要固执己见
+- human 不替你决定立场——它提供信息，最终判断仍由你基于论据做出
+
+看到 human 消息时按正常规则回应：有话 → message，无话 → freezing/pass。
+
+## message 质量
+
+- **有论据**：给出理由/事实/例子支持你的观点，不要只喊口号
+- **回应已有观点**：如果分析中有你要回应/反驳的观点，明确指出来——
+  **必须写 `作者/序号`**（如 `回应 a/0003`），不能只说"某人"或模糊描述；
+  不要无视他人观点自说自话
+- **不重复**：不要重复已说过的观点；要么补充新角度，要么同意（freezing）
+- **聚焦分歧**：有分歧时聚焦分歧点，不要全面重述
+
+{MAIN_PI_CWD_SECTION}

package/templates/agent.md.tpl

@@ -0,0 +1,9 @@
+# Pi 多视角参与者 {AGENT_NAME}
+
+你是 {AGENT_NAME}，参与一次 {N}-视角协同分析。
+参与者：{PARTICIPANTS_DISPLAY}。分析主题见 question.md。
+{STANCE_REF}按 AGENTS.md 的协议规则行事。
+{MODEL_BODY}
+
+## 你的视角任务书
+

package/templates/gitignore.tpl

@@ -0,0 +1,7 @@
+# 本地配置（gitignored——每个 clone 各自持有；本文件 .gitignore 自身会提交）
+.pi/
+pi-agent.json
+AGENTS.md
+
+# 注：status-*.json 实际写在讨论根（workdir 父级，meeting_loop.py），不在
+# work clone 内——此处无需忽略

package/templates/spec-readme.md.tpl

@@ -0,0 +1,87 @@
+# 分析规格目录（--prepare 生成）
+
+这个目录定义一次多视角分析的全部内容。编辑下面的文件，然后启动分析。
+
+**所有文件的第一行都是说明文字，不会注入到分析环境（会被跳过）。正文从第二行开始写。**
+
+## question.md —— 分析主题（必填）
+
+**作用**：整个文件（跳过第一行）会变成分析环境里的 `question.md`——所有
+agent 从这里了解主题与任务边界。
+
+在这里写清**应该做什么**——任务类型决定产出形态，不要依赖上下文自明：
+
+- **审阅** → 提出意见（哪些有问题、为什么）
+- **改进建议** → 说出建议（改什么、怎么改）
+- **修改** → 说明哪些可以修改、哪些需要修改（有改动权限的边界）
+
+同时写明：分析对象（文件/模块/问题）、期望的产出（如"改进建议清单"）、
+是否需要达成一致。
+
+**为什么重要**：每个 agent 的上下文里有发起分析的对话历史（默认
+budget 模式：按预算裁剪+折叠）——其中的开发过程、未完成事项都可能被
+agent 当成"该做的事"。question.md 的任务定义越明确，agent 越不会跑偏
+去做上下文里的其它事情。
+
+范例（从第二行开始写）：
+
+    # 分析主题：评审 src/calculator.py 的代码质量
+
+    任务：审阅 src/calculator.py，从各自视角提出评审意见（本轮只
+    提意见，不修改代码）。指出问题、说明理由；
+    对其它视角的观点可以认同或反驳，但要用自己视角的论据。
+    最终需要对"问题清单"达成一致。
+
+## background.md —— 边界与约定（可选）
+
+**作用**：注入每个 agent 的协议文件（AGENTS.md 背景节）。
+
+fork 机制已让每个 agent 携带发起分析时的对话上下文（默认 budget 模式：
+按预算裁剪+折叠），所以**不需要**在这里复述对话内容。这里只写**显式
+约定的边界**，例如：
+
+- 分析只聚焦某些方面（"不讨论 API 设计"）
+- 已知的硬约束（"必须保持向后兼容"）
+- 用户指定的优先级（"性能问题优先级最高"）
+
+没有就留空。
+
+## models.md —— 模型配置（可选）
+
+每行：`agent名: model[, variant]`。model 默认 default（继承本机默认），
+variant 默认 max。只有不用默认/-max 时才需要改。
+
+## agents/X.md —— 视角任务书（每个 agent 一个）
+
+**作用**：定义该 agent 的**视角**——它用哪副眼镜看分析对象。
+
+**只写视角本身**。以下内容由脚本从机制生成，**不要写进任务书**
+（写进去会重复，且容易与实际漂移——文件名才是 agent 名的唯一来源）：
+
+- 身份与参与者（"你是 X"、"参与者有 A、B、C"）——脚本按文件名注入
+- 消息格式、frontmatter 字段、写文件路径、独立参与者纪律——见协议文件
+  （AGENTS.md，脚本注入）
+
+写好视角任务书的要点（实测有效的措辞模式）：
+
+1. **单一视角**：明确写出这个 agent 用什么 lenses 看（性能/简单化/
+   安全/成本/用户体验/……），并要求"所有观点必须从该视角出发"
+2. **不越界**：写明"其它视角由别的参与者负责，你不要越界展开"——
+   实验证明这句能避免视角串味（不要列举具体是哪几个视角——
+   参与者会变，列举就会过期）
+3. **交锋义务**：写明"对其它视角的观点可以认同或反驳，但要用本视角
+   的论据"——防止附和式讨论
+
+范例（agents/性能.md 全文——身份那句由脚本加，不在正文里）：
+
+    你的所有观点必须从性能角度出发：复杂度、热点、不必要的计算、扩展性。
+    如果其它视角的优化建议会显著损害性能，你应该明确反对并说明理由。
+    其它视角由别的参与者负责，你不要越界展开。
+    对其它视角的观点可以认同或反驳，但要用本视角的论据。
+
+视角之间**互补或对立都可以**——对立视角产生的分歧正是多视角分析的价值。
+
+## 下一步
+
+编辑完成后启动分析：`scripts/mv.sh --start <本目录绝对路径>`
+（或告诉主 pi "继续"，由它代为执行）。