pi-multi-viewers 0.2.2 → 0.4.0

package/start_discussion.py

@@ -3,7 +3,7 @@
 
 用法：
   python3 start_discussion.py --dir mymeet --topic "主题" --agents a,b \
-      [--stances '{"a": "立场1", "b": "立场2"}'] [--start] [--pure] \
+      [--stances '{"a": "立场1", "b": "立场2"}'] [--start] [--extensions] \
       [--models '{"a": "provider/model"}'] [--max-meeting 10] [--max-rr 7]
 
 复杂内容用 spec 规格目录（设计 16，与 CLI 内容参数互斥）：
@@ -70,8 +70,11 @@ def _spec_models(spec_dir, participants):
     """解析 models.md（容错，用户 8024/9204 定）：返回 {agent: (model, variant)}。
 
     每行格式：`agent名: model, variant`（model 与 variant 逗号分隔）。
-    - model 缺省/'default' → None（创建时填本机默认模型）
-    - variant 缺省/'default'/'max' → 'max'（默认档，专业用户才改）
+    - model 缺省/'default' → None（创建时填本机默认模型）——`default`
+      这个别名**只在 model 槽有意义**
+    - variant 缺省 → DEFAULT_THINKING；**没有 `default` 别名**（同词在相邻
+      两行反义会让读者必错；且空已是缺省，别名不增加表达力）——写了 `default`
+      就按原值透传给 pi（可见失败，而非静默重解释）
     容错：空行/无 ':'/agent 不在 participants → 跳过；单字段行只有 model。
     规则：第一行说明跳过（_spec_read）。
     """
@@ -93,8 +96,13 @@ def _spec_models(spec_dir, participants):
         parts = [p.strip() for p in rest.split(",")]
         model = parts[0] if parts and parts[0] else ""
         variant = parts[1] if len(parts) > 1 else ""
+        # `default` **只在 model 槽有意义**（= 继承本机）。variant 槽不做
+        # 同名别名（e2e17 评审 §7.2：相邻两行同词反义——model 的 default
+        # = 继承，variant 的 default = max，按上一行直觉读下一行必错）；
+        # 且别名并不增加表达力：空 = max 已是缺省。写 `default` 不再是
+        # 别名 → 原值传给 pi（可见的失败，而不是静默重解释成 max）。
         m = None if (not model or model == "default") else model
-        v = "max" if (not variant or variant == "default") else variant
+        v = variant or meeting_fs.DEFAULT_THINKING
         out[agent] = (m, v)
     return out
 
@@ -303,21 +311,23 @@ def setup_environment(args, participants, base, spec_dir=None,
                    for p in participants}
     agent_extra = {k: v for k, v in agent_extra.items() if v}
     # models：spec 模式从 models.md 读（自包含，{agent: (model, variant)}），
-    # CLI --models 已互斥（{agent: model} 旧格式——variant 用默认 max）
+    # CLI --models 已互斥（{agent: model} 旧格式——variant 用默认档）
     if spec_dir:
         models = _spec_models(spec_dir, participants)
     else:
-        models = {p: (m, "max") for p, m in (args.models or {}).items()}
-    # default 模型 → 创建时实时获取 Pi 默认模型填入：
-    # pi-agent.json 带 model 后，meeting_loop 才会传 --model；
-    # 骨架期 models.md 仍写 default（--spec-gen 不获取），创建时（--spec）
-    # 才解析。运行期固化不变（环境自包含）。
-    if spec_dir:
-        dm = _default_model()
-        if dm:
-            for p in participants:
-                if p not in models or models[p][0] is None:
-                    models[p] = (dm, models.get(p, (None, "max"))[1])
+        models = {p: (m, meeting_fs.DEFAULT_THINKING)
+                  for p, m in (args.models or {}).items()}
+    # 归一：每个 participant 都有 (model, variant) 条目，**此后只读**——
+    # 此前 :320 补默认模型与 :384 写 pi-agent.json 各自再写一遍
+    # `models.get(p, (None, "max"))`（同层同义重复，值两处声明，e2e17
+    # 评审 §7.10）。
+    # default 模型 → 创建时实时获取 Pi 默认模型填入：pi-agent.json 带
+    # model 后，meeting_loop 才会传 --model；骨架期 models.md 仍写 default
+    # （--spec-gen 不获取），创建时（--spec）才解析。运行期固化不变。
+    dm = _default_model() if spec_dir else None
+    for p in participants:
+        m, v = models.get(p, (None, meeting_fs.DEFAULT_THINKING))
+        models[p] = (m or dm, v)
     # stance_ref（agent 定义"立场见 question.md"提示）：spec 模式一律保留
     # （设计 16.6：无法程序判断 question.md 有无立场节 → 一律提示；
     # 互斥下 CLI stances 必为 None，传占位 dict 触发生成）
@@ -340,7 +350,7 @@ def setup_environment(args, participants, base, spec_dir=None,
     # 共享配置（work-a 提交，setup commit 进 bare）
     with open(os.path.join(wa, "protocol.json"), "w") as f:
         json.dump(gen_protocol(spec_topic or args.topic, participants, args.max_meeting,
-                               args.max_rr, args.pure, args.result_writer,
+                               args.max_rr, args.extensions, args.result_writer,
                                args.stall_timeout,
                                fork_source=getattr(args, "fork_source", None),
                                fork_cwd=os.getcwd(),
@@ -381,14 +391,14 @@ def setup_environment(args, participants, base, spec_dir=None,
         with open(os.path.join(workdir, "AGENTS.md"), "w") as f:
             f.write(gen_agents_md(args, p, participants, spec_background,
                                  main_pi_cwd=os.getcwd()))
-        mv = models.get(p, (None, "max"))
+        mv = models[p]        # 归一后必有条目（见上方归一循环）
         with open(os.path.join(workdir, ".pi/agent", f"{p}.md"), "w") as f:
             f.write(gen_agent_def(p, participants, {p: mv[0]} if mv[0] else None,
                                   stances_arg, agent_extra.get(p)))
         with open(os.path.join(workdir, "pi-agent.json"), "w") as f:
             json.dump({
                 "model": mv[0] or "",
-                "thinking": mv[1] if mv[1] else "max",
+                "thinking": mv[1] or meeting_fs.DEFAULT_THINKING,
                 "prompt_file": f".pi/agent/{p}.md",
             }, f, indent=2, ensure_ascii=False)
 
@@ -409,7 +419,8 @@ def setup_environment(args, participants, base, spec_dir=None,
     rw = args.result_writer or participants[-1]
     print(f"[setup] 环境就绪: {base}（{len(participants)} agents: {', '.join(participants)}）")
     print(f"[setup] resultWriter={rw}, maxMeeting={args.max_meeting}, maxRR={args.max_rr}, "
-          f"立场={'有' if (args.stances or spec_dir) else '无'}, pure={args.pure}")
+          f"立场={'有' if (args.stances or spec_dir) else '无'}, "
+          f"extensions={args.extensions}")
 
 
 def _preserve_result_md(base):
@@ -539,7 +550,9 @@ def main():
                              "protocol.json，各 agent 首唤由本地生成 fork "
                              "源挂载主上下文；不传 = 从主 pi 环境自动解析"
                              "（PI_SESSION_ID；解析失败明确报错）")
-    parser.add_argument("--pure", action="store_true", help="--pure 模式（禁外部插件）")
+    parser.add_argument("--extensions", action="store_true",
+                        help="让 agents 加载外部扩展（默认零扩展：不加载任何"
+                             "外部扩展/技能/prompt-template/主题）")
     parser.add_argument("--start", action="store_true", help="创建后启动讨论")
     parser.add_argument("--skip-setup", action="store_true",
                         help="跳过环境生成，只启动已有环境（需 --dir）")
@@ -691,12 +704,12 @@ def main():
             workdir = os.path.join(base, f"work-{p}")
             cmd = [sys.executable, os.path.join(base, "meeting_loop.py"),
                    workdir, p]
-            if args.pure:
-                cmd.append("--pure")
+            if args.extensions:
+                cmd.append("--extensions")
             # 配额（max-meeting/max-rr/stall-timeout）是环境属性：创建时
             # 固化在 protocol.json，启动继承（loop 读 protocol 优先）。
             # 不传 CLI —— 避免无条件覆盖 protocol.json 的固化值
-            # （审核 C1：配额单一事实源；与 pure 处理一致）
+            # （审核 C1：配额单一事实源；与 extensions 处理一致）
             with open(os.path.join(base, f"loop-{p}.log"), "w") as f:
                 procs.append(subprocess.Popen(cmd, stdout=f,
                                               stderr=subprocess.STDOUT,

package/templates/spec-readme.md.tpl

@@ -42,14 +42,19 @@ fork 机制已让每个 agent 携带发起分析时的对话上下文（默认 b
 
 - 分析只聚焦某些方面（"不讨论 API 设计"）
 - 已知的硬约束（"必须保持向后兼容"）
-- 用户指定的优先级（"性能问题优先级最高"）
+- 用户指定的优先级（"效率问题优先级最高"）
 
 没有就留空。
 
 ## models.md —— 模型配置（可选）
 
-每行：`agent名: model[, variant]`。model 默认 default（继承本机默认），
-variant 默认 max。只有不用默认/-max 时才需要改。
+每行：`agent名: model, variant`（**两个槽都显式写出**，一眼可见本场跑在
+什么模型/档位上）。model 写 `default` = 继承本机默认；variant 不写 =
+`max`。想换档位（如 `high`）改这一行即可——**逐 agent 一行**，可以只改
+某一个视角。
+
+> 这里写的就是**声明值**；实际生效值由 pi 解析（它自己的优先级链）。
+> `--report` 会把声明值与 session 里的生效值对照列出。
 
 ## agents/X.md —— 视角任务书（每个 agent 一个）
 
@@ -64,7 +69,7 @@ variant 默认 max。只有不用默认/-max 时才需要改。
 
 写好视角任务书的要点（实测有效的措辞模式）：
 
-1. **单一视角**：明确写出这个 agent 用什么 lenses 看（性能/简单化/
+1. **单一视角**：明确写出这个 agent 用什么 lenses 看（效率/简单化/
    安全/成本/用户体验/……），并要求"所有观点必须从该视角出发"
 2. **不越界**：写明"其它视角由别的参与者负责，你不要越界展开"——
    实验证明这句能避免视角串味（不要列举具体是哪几个视角——
@@ -72,10 +77,15 @@ variant 默认 max。只有不用默认/-max 时才需要改。
 3. **交锋义务**：写明"对其它视角的观点可以认同或反驳，但要用本视角
    的论据"——防止附和式讨论
 
-范例（agents/性能.md 全文——身份那句由脚本加，不在正文里）：
+范例（agents/效率.md 全文——身份那句由脚本加，不在正文里；本例内容较长，
+要点是"把该视角盯住的东西逐项写明"）：
+
+    你的所有观点必须从运行效率角度出发：时间效率（一次分析从开始到收尾要
+    多久、哪些环节在吃时间、哪些等待可消除）与运行效率（不必要的计算与
+    等待、可并行而串行的部分、随规模增长的代价）。
+    能用已有数据说出"省多少、占多少比例"就说；拿不到数据就写明需要什么
+    数据，不要凭感觉下结论。
 
-    你的所有观点必须从性能角度出发：复杂度、热点、不必要的计算、扩展性。
-    如果其它视角的优化建议会显著损害性能，你应该明确反对并说明理由。
     其它视角由别的参与者负责，你不要越界展开。
     对其它视角的观点可以认同或反驳，但要用本视角的论据。