magic-agent 1.0.49 → 1.0.109

package/internal/cli/ask.go

@@ -133,6 +133,41 @@ type askOptions struct {
 	autoModeEnv    []string // 第 3 档分类器的受信边界描述（autoMode.environment）
 	permDeny       []string // 追加 deny 规则（permissions.deny，所有档位生效）
 	permAsk        []string // 追加 ask 规则（permissions.ask，强制人工审批）
+
+	/* 团队模式（2026-10-21，见 internal/team）。
+	 *
+	 * 它是**会话层的一种运行模式**，不是新引擎：主引擎（-e）拆任务 → 子引擎分头执行
+	 * → 主引擎汇总。默认关（用户定稿：「默认不开启」）；开关在移动端右上角的运行设置里。
+	 *
+	 * 与 --keep-alive 的关系：团队模式不接追加（子任务不共享上下文、也不该被追问），
+	 * 所以开了它之后常驻会话自动不生效（见 runStreamAsk 里的 kaEnabled 判定）。 */
+	team          bool          // --team：开启团队模式
+	teamPlanOnly  bool          // --team-plan-only：只出计划与任务书，不执行
+	teamParallel  int           // --team-parallel：并发度（默认 4）
+	teamTaskTO    time.Duration // --team-task-timeout：单子任务超时（0 = 按总超时推算）
+	teamRoutes    []string      // --team-route <kind>=<engine>[/<model>]，可重复
+	teamRunDir    string        // --team-run-dir：覆盖运行目录父级
+	teamPerm      string        // --team-permission：子任务权限上限（默认 accept-edits）
+	teamAdaptive  bool          // --team-adaptive：执行后按失败 / open 项再规划一轮
+	teamSplit     string        // --team-split：拆解粒度 coarse | standard | fine
+	teamSplitCode bool          // --team-split-code：简单代码也拆成独立子任务
+	teamRules     []string      // --team-rule role:<name>=<规则>，可重复
+
+	/* 会话自动聚合成需求（2026-10-22；见 internal/requirements）。
+	 *
+	 * 读与写分成两个 flag：读（列表）客户端每刷一次都调，绝不能顺手触发模型；
+	 * 写（归纳）几秒到几分钟，只在轮末防抖或用户手点时跑。
+	 *
+	 * 值都可以留空 —— 读留空 = 列全部工作区，写留空 = 当前目录，
+	 * 所以派发一律用 flagChanged 判断（看「传过没有」而不是「值非空」）。 */
+	requirements    string        // --requirements [<ws|dir>]：读清单
+	consolidateReqs string        // --consolidate-requirements [<ws|dir>]：跑一轮归纳
+	reqForce        bool          // --requirement-force
+	reqAll          bool          // --requirement-all：全量重放
+	reqEngine       string        // --requirement-engine（默认 llm）
+	reqModel        string        // --requirement-model
+	reqTimeout      time.Duration // --requirement-timeout
+	reqAuto         bool          // --requirement-auto：自动归纳，不触发首次初始化
 }
 
 // newAskOptions 返回带默认值的选项集。
@@ -202,9 +237,37 @@ func bindAskFlags(cmd *cobra.Command, opts *askOptions) {
 	f.BoolVar(&opts.events, "events", false, "配合 --stream：事件流带契约版本与行号（每行加 v / seq，并先发一行 ready），供客户端消费；老消费者不要开（形状与 --stream 不同）")
 	f.BoolVar(&opts.control, "control", false, "配合 --stream：从 stdin 读 NDJSON 控制命令（ping / interrupt / stop / answer），让调用方能打断长任务、回审批")
 	f.BoolVar(&opts.noThinking, "no-thinking", false, "流式模式下不转发思考过程增量")
+	bindTeamFlags(cmd, opts)
+	bindRequirementFlags(cmd, opts)
 	bindPermissionFlags(cmd, opts)
 }
 
+// bindTeamFlags 注册团队模式的 flags（默认全关 —— 用户定稿「默认不开启」）。
+//
+// 为什么这些参数要能一个一个给：客户端（移动端的「我的 → 团队模式」）把各类任务 / 各角色的
+// 引擎/模型配置存在本地，每次请求随 body 下发，插件再翻译成 --team-route。core 侧
+// 因此必须是**无状态**的：配置跟着请求走，不落 core 配置文件。
+func bindTeamFlags(cmd *cobra.Command, opts *askOptions) {
+	f := cmd.PersistentFlags()
+	f.BoolVar(&opts.team, "team", false, "团队模式：主引擎拆任务 → 子引擎分头执行 → 主引擎汇总（需配合 --stream；默认关）")
+	f.BoolVar(&opts.teamPlanOnly, "team-plan-only", false, "配合 --team：只生成计划文档与任务书，不执行子任务（调试 / 先确认方案）")
+	f.IntVar(&opts.teamParallel, "team-parallel", 4, "配合 --team：同时最多跑几个子任务（默认 4）")
+	f.DurationVar(&opts.teamTaskTO, "team-task-timeout", 0, "配合 --team：单个子任务超时（0 = 总超时的 1/2，上限 20m）")
+	f.StringArrayVar(&opts.teamRoutes, "team-route", nil,
+		"配合 --team：给某类子任务或某个角色指定引擎/模型，形如 image=llm/hunyuan-image-3.0 或 role:coder=claude/sonnet（可重复；类别：plan|text|code|image|video|game；角色用 role:<name>）")
+	f.StringVar(&opts.teamRunDir, "team-run-dir", "", "配合 --team：覆盖运行目录的父目录（空 = 选了空间落 <空间>/.magic/team，否则落 ~/.magic-agent/team）")
+	f.StringVar(&opts.teamPerm, "team-permission", string(agent.PermissionAcceptEdits),
+		"配合 --team：子任务的权限上限（默认 accept-edits —— 子任务不该继承主会话的完全访问）")
+	f.BoolVar(&opts.teamAdaptive, "team-adaptive", true,
+		"配合 --team：第一轮执行后按失败与未解决项再规划一轮补充任务（默认开；只补一轮、最多 3 个）")
+	f.StringVar(&opts.teamSplit, "team-split", "",
+		"配合 --team：拆解粒度 coarse（最多 3 个）| standard（6，默认）| fine（10）")
+	f.BoolVar(&opts.teamSplitCode, "team-split-code", false,
+		"配合 --team：简单代码也拆成独立子任务（默认关：简单代码由主引擎直接给出）")
+	f.StringArrayVar(&opts.teamRules, "team-rule", nil,
+		"配合 --team：改写某个角色「这类任务适合什么」，形如 role:coder=只拆多文件、要构建或测试的改动（可重复）")
+}
+
 // bindPermissionFlags 注册四档权限模型的 flags（仅 claude / codebuddy / dsh 生效）。
 //
 // 默认档 full 是**刻意**的：改造前 claude/codebuddy 在 --tools 非 off 时恒传
@@ -462,6 +525,13 @@ func resolvePermissionTier(engineName, raw string, explicit bool) (agent.Permiss
 
 // runAsk ask 主流程（非流式）。
 func runAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
+	if opts.team {
+		// 团队模式靠事件流才能把「谁在干什么」呈现出来（子任务的委派卡、增量正文），
+		// 一次性 envelope 装不下这些过程。明确拒绝，而不是悄悄忽略 --team。
+		return &usageError{fmt.Errorf(
+			"--team 需要 --stream（团队模式的过程靠事件流呈现：每个子任务在界面上是一张委派卡）；" +
+				"加上 --stream 即可，或去掉 --team 走单引擎")}
+	}
 	engine, format, req, err := prepareAsk(cmd, args, opts)
 	if err != nil {
 		return err
@@ -609,6 +679,14 @@ func runStreamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 		} else {
 			sessionLog = sw
 			defer func() { sessionLog.close() }()
+			// 续接（`--session <id>`）时 id 一开始就知道：先把它推给 writer，
+			// 让日志**从头就写进终名文件**。否则会先落 <run_id>.jsonl（seq 从 1），
+			// 等引擎吐 id 再合并进 <session_id>.jsonl —— 同一文件里 seq 出现回落，
+			// 客户端的增量游标（after=旧轮末位）会把新一轮整段滤掉，画布看着
+			// 「永远已追平」（用户实测：掌天瓶任务对话不刷新）。
+			if id := strings.TrimSpace(opts.session); id != "" {
+				sessionLog.setSessionID(id)
+			}
 		}
 	}
 	// 把 session_id 推到 writer：CLI 这边的 OnSessionID 回调（引擎流里见到 init 行就调）
@@ -662,8 +740,9 @@ func runStreamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 			Kind: string(ev.Kind), Text: ev.Text, Name: ev.Name, ID: ev.ID,
 			ToolKind: toolKindOfEvent(ev), Ask: ev.Ask,
 			ItemID: ev.ItemID, ItemRevision: ev.ItemRevision,
-			Status: string(ev.Status),
-			Error:  ev.Error, Reason: ev.Reason,
+			Status: string(ev.Status), Parent: ev.Parent,
+			SubSessionID: ev.SubSessionID,
+			Error:        ev.Error, Reason: ev.Reason,
 		})
 	}
 	if format == agent.FormatJSON {
@@ -822,16 +901,27 @@ func runStreamAsk(cmd *cobra.Command, args []string, opts *askOptions) error {
 	   界面上该显示「等审批」而不是「生成中」。用户作答、或这一轮的任何后续事件到达时
 	   回到 running。落点选在这里，是因为它同时罩住两条 onEvent（--stream 与 --events），
 	   不必在两个分支里各写一遍（漏一个就会有一条通道的状态是假的）。
+	   ⚠️ 常驻会话**本轮结束**时要写 idle（2026-10-21）：进程还在等 --append，但这一轮
+	   已经跑完 —— 继续写 running 会让别的端（移动端跟进 / 串行门）以为还在跑，PC 却按
+	   事件流显示「已完成」，两边状态就此分叉（用户 2026-10-21 报障：移动端排队追问永不
+	   下发）。下一轮第一个事件到达自然回到 running。
+	   条件只看 ka 是否存在、**不看 --idle**：桌面端/移动端恒传 `--idle 0`（本轮结束就
+	   收工），但引擎收尾与进程退出可能拖上几分钟 —— 这段空窗正是登记表 running、界面
+	   「已完成」并存的来源。写 idle 之后再收尾写 done，两步都覆盖。
 	   写入很快（状态没变时 Mark 直接返回，一轮最多两次落盘），见 session.Handle.Mark。 */
+	idleAfterTurn := ka != nil
 	if h != nil {
 		inner := onEvent
 		onEvent = func(ev agent.StreamEvent) {
 			// 会话锚点：引擎把 id 挂在事件上时同样立刻回填（覆盖不调 OnSessionID 的引擎，
 			// 见上面那段注释）。空 id 由 SetSessionID 自己跳过。
 			h.SetSessionID(ev.SessionID)
-			if ev.Kind == agent.KindAsk {
+			switch {
+			case ev.Kind == agent.KindAsk:
 				h.Mark(session.StateWaitingApproval)
-			} else {
+			case ev.Kind == agent.KindTurnEnd && idleAfterTurn:
+				h.Mark(session.StateIdle)
+			default:
 				h.Mark(session.StateRunning)
 			}
 			inner(ev)

package/internal/cli/contract_test.go

@@ -6,6 +6,7 @@ import (
 	"testing"
 
 	"github.com/darren/magic-agent/internal/agent"
+	"github.com/darren/magic-agent/internal/team"
 )
 
 // contractRow 是 --engines / --contract 每一行里本测试关心的字段。
@@ -27,8 +28,14 @@ func TestContractEnvelope(t *testing.T) {
 	}
 	var env struct {
 		ContractVersion int           `json:"contractVersion"`
+		Version         string        `json:"version"`
 		Features        []string      `json:"features"`
 		Engines         []contractRow `json:"engines"`
+		TeamRoles       []struct {
+			Name string `json:"name"`
+			Kind string `json:"kind"`
+			Duty string `json:"duty"`
+		} `json:"teamRoles"`
 	}
 	if err := json.Unmarshal([]byte(stdout), &env); err != nil {
 		t.Fatalf("解析 --contract 输出失败: %v（原始输出：%s）", err, stdout)
@@ -36,6 +43,11 @@ func TestContractEnvelope(t *testing.T) {
 	if env.ContractVersion != agent.ContractVersion {
 		t.Errorf("contractVersion = %d want %d", env.ContractVersion, agent.ContractVersion)
 	}
+	/* 版本号（2026-10-22 只增字段）：移动端「我的」页显示它。空 = 客户端只能显示「—」，
+	   所以这里必须非空（测试里是 internal/cli.Version 的默认值，构建时由 ldflags 覆盖）。 */
+	if env.Version == "" {
+		t.Error("version 不应为空：移动端「我的」页要显示当前 core 版本")
+	}
 	// 核心级通道能力：客户端据此判断这台 core 支不支持 --events / --control。
 	for _, want := range []string{agent.FeatureSessionEvents, agent.FeatureSessionControl} {
 		found := false
@@ -52,6 +64,20 @@ func TestContractEnvelope(t *testing.T) {
 	if got, want := len(env.Engines), len(agent.Engines()); got != want {
 		t.Errorf("engines 行数 = %d want %d", got, want)
 	}
+	/* 团队角色清单（2026-10-22 新增，只增字段不升 contractVersion）：
+	   移动端「团队模式」页据此渲染角色路由行（缩进在所属类别下），客户端不许硬编码角色名。 */
+	names := team.RoleNames()
+	if got, want := len(env.TeamRoles), len(names); got != want {
+		t.Fatalf("teamRoles 行数 = %d want %d", got, want)
+	}
+	for i, r := range env.TeamRoles {
+		if r.Name != names[i] {
+			t.Errorf("teamRoles[%d].name = %q want %q（顺序即界面顺序）", i, r.Name, names[i])
+		}
+		if r.Kind == "" || r.Duty == "" {
+			t.Errorf("%s: kind/duty 不应为空（移动端要展示）：%+v", r.Name, r)
+		}
+	}
 	for _, row := range env.Engines {
 		if row.Engine == "" {
 			t.Errorf("有一行缺 engine 字段：%+v", row)

package/internal/cli/events.go

@@ -191,13 +191,17 @@ func (s *eventSink) notice(kind string, attrs map[string]any) error {
 // 老事件（turn_end 之外的轮次事件）不带这些字段时与历史逐字节一致。
 func streamEventPayload(ev agent.StreamEvent) any {
 	return struct {
-		Type      string            `json:"type"`
-		Text      string            `json:"text"`
-		Name      string            `json:"name,omitempty"`
-		ID        string            `json:"id,omitempty"`
-		ToolKind  string            `json:"tool_kind,omitempty"`
-		SessionID string            `json:"session_id,omitempty"`
-		Ask       *agent.AskRequest `json:"ask,omitempty"`
+		Type      string `json:"type"`
+		Text      string `json:"text"`
+		Name      string `json:"name,omitempty"`
+		ID        string `json:"id,omitempty"`
+		ToolKind  string `json:"tool_kind,omitempty"`
+		SessionID string `json:"session_id,omitempty"`
+		/* 子会话 id（2026-10-21，团队模式）：非空 = 这条事件来自某个**绑定在主会话
+		   下面的子任务会话**。它只是展示/留档用，不参与会话锚点（锚点只认
+		   session_id）。omitempty：非团队事件不带它，老消费者字段集不变。 */
+		SubSessionID string            `json:"sub_session_id,omitempty"`
+		Ask          *agent.AskRequest `json:"ask,omitempty"`
 		/* 状态收敛四元组（2026-10-02，对齐 agents-anywhere 的 timeline item）。
 		   消费方按 (item_id, item_revision) 覆盖式 upsert 即可：
 		   同一 item 的多个 partial 帧 + 最后一个 final 帧，
@@ -206,6 +210,11 @@ func streamEventPayload(ev agent.StreamEvent) any {
 		ItemRevision uint64 `json:"item_revision,omitempty"`
 		Status       string `json:"status,omitempty"`
 		Snapshot     string `json:"snapshot,omitempty"`
+		/* 父委派 id（2026-10-21，团队模式）：非空 = 这条事件属于 id 为它的委派卡。
+		   语义与 claude 系原生的 parent_tool_use_id 一致，渲染层本来就按它把子事件
+		   挂进委派卡的嵌套区（见 shared/conv/09-stream-apply.js 的 evParent）。
+		   omitempty：主会话自己的事件不带它，老消费者字段集不变。 */
+		Parent string `json:"parent,omitempty"`
 		/* 异常收尾（仅 turn_failed）：Error 是完整错误链，Reason 是最内层根因，
 		   与 -o json 的失败 envelope 同源（都走 agent.ReasonOf）。 */
 		Error  string `json:"error,omitempty"`
@@ -217,11 +226,13 @@ func streamEventPayload(ev agent.StreamEvent) any {
 		ID:           ev.ID,
 		ToolKind:     toolKindOfEvent(ev),
 		SessionID:    ev.SessionID,
+		SubSessionID: ev.SubSessionID,
 		Ask:          ev.Ask,
 		ItemID:       ev.ItemID,
 		ItemRevision: ev.ItemRevision,
 		Status:       string(ev.Status),
 		Snapshot:     ev.Snapshot,
+		Parent:       ev.Parent,
 		Error:        ev.Error,
 		Reason:       ev.Reason,
 	}

package/internal/cli/keepalive_test.go

@@ -177,6 +177,75 @@ func TestKeepAliveIsDefaultForStreaming(t *testing.T) {
 	}
 }
 
+// idleWindowEngine 模拟真实引擎的收尾空窗：turn_end 之后要过一阵才返回
+// （claude 收到 result 后进程还可能拖几分钟）。测试就在这段窗口里读登记表。
+type idleWindowEngine struct {
+	name  string
+	after time.Duration
+}
+
+func (e *idleWindowEngine) Name() string           { return e.name }
+func (e *idleWindowEngine) Detect() (bool, string) { return true, "fake://" + e.name }
+
+// CapabilityFamily：常驻会话只对 claude / codebuddy 家族生效（agent.AppendSupportOf），
+// 假引擎用这个名字接到 claude 的能力表上，不必借用会被别的用例先注册的真名。
+func (e *idleWindowEngine) CapabilityFamily() string { return "claude" }
+func (e *idleWindowEngine) Complete(context.Context, agent.Request) (agent.Response, error) {
+	return agent.Response{Text: "ok", Model: "fake-model"}, nil
+}
+func (e *idleWindowEngine) Stream(_ context.Context, _ agent.Request, onEvent func(agent.StreamEvent)) (agent.StreamResult, error) {
+	onEvent(agent.StreamEvent{Kind: agent.KindText, Text: "ok"})
+	onEvent(agent.StreamEvent{Kind: agent.KindTurnEnd})
+	time.Sleep(e.after)
+	return agent.StreamResult{
+		Response: agent.Response{Engine: e.name, Text: "ok", Model: "fake-model", SessionID: "sid-idle-window"},
+	}, nil
+}
+
+// 常驻会话本轮结束后必须写 idle，且**与 --idle 取值无关**（2026-10-21 报障）：
+// 桌面端恒传 `--idle 0`，写 idle 的条件若带上 opts.idle > 0 就对真实调用完全不生效 ——
+// 登记表在引擎收尾那几分钟里仍是 running，移动端跟进据此认为上一轮还在跑，
+// 排队追问永不下发（PC 却按事件流显示「已完成」）。
+func TestIdleMarkedAfterTurnWithZeroIdle(t *testing.T) {
+	dir := shortSessionsDir(t)
+	t.Setenv(session.EnvDir, dir)
+	eng := &idleWindowEngine{name: "fake-idle-zero", after: 2 * time.Second}
+	registerFake(eng)
+
+	done := make(chan error, 1)
+	go func() {
+		_, _, err := runAskCmd(t, "", "--save-registry", "-e", eng.name, "--stream", "--idle", "0", "-p", "一轮")
+		done <- err
+	}()
+
+	var got string
+	deadline := time.Now().Add(10 * time.Second)
+	for time.Now().Before(deadline) {
+		if recs := mustListSessions(t, dir); len(recs) == 1 {
+			got = recs[0].State
+			if got == session.StateIdle {
+				break
+			}
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	if got != session.StateIdle {
+		t.Fatalf("--idle 0 时本轮结束后登记表应为 idle，实际 %q", got)
+	}
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatalf("收尾报错: %v", err)
+		}
+	case <-time.After(20 * time.Second):
+		t.Fatal("没收工")
+	}
+	// idle 只是中途态：进程退出后要落到终态 done。
+	if recs := mustListSessions(t, dir); len(recs) != 1 || recs[0].State != session.StateDone {
+		t.Fatalf("收尾后应为 done，实际 %+v", recs)
+	}
+}
+
 // --keep-alive=false 关掉常驻：不建 socket，turn 结束即退出（老行为）。
 func TestKeepAliveCanBeDisabled(t *testing.T) {
 	dir := shortSessionsDir(t)

package/internal/cli/requirements.go

@@ -0,0 +1,119 @@
+package cli
+
+// requirements.go - `--requirements` / `--consolidate-requirements`：
+// 「把会话自动聚合成需求」收成 core 标准能力后的**CLI 出口**。
+//
+// 为什么是两条命令而不是一条带动作参数的：
+//
+//	· `--requirements [<ws|dir>]`  读：工作区 → 模块 → 功能点清单（和 --sessions 同族，
+//	  客户端列表页每刷一次都会调，**绝不能**顺手触发 LLM）；
+//	· `--consolidate-requirements [<ws|dir>]`  写：跑一轮归纳（会调模型，几秒到几分钟）。
+//
+// 读与写的代价差三个数量级，混成一个命令之后「刷新列表」就变成了「每次都烧一次模型」。
+//
+// 与 `--summarize-title` 同一套理由：core 不跑服务，调用方（magic-client / 桌面 / 移动端）
+// exec 这两条命令即可，不必碰 ~/.magic-agent/requirements 的磁盘格式。
+//
+// 退出码：
+//
+//	0  成功（读：拿到清单；写：归纳完成或无事可做 noop）
+//	1  失败（引擎不可用 / 模型输出不可解析 / 工作区不存在）
+//	2  参数错（只给了 --requirement-force 之类没给主 flag）
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/darren/magic-agent/internal/requirements"
+)
+
+// runRequirements 列需求清单：`--requirements all|<ws_id|目录>`。
+//
+// 值必须是显式的（all = 全部工作区，或某个 ws id / 目录路径）：
+// cobra 的 string flag 不能"传了 flag 不带值"，与其让 `--requirements` 报
+// "flag needs an argument"，不如把「全部」写成一个能看见的取值。
+//
+// ⚠️ 只读：不摄入新记忆、不触发归纳。清单里的 pending 是「已摄入但还没归纳」的条数，
+// 摄入发生在归纳那一轮（见 requirements.Consolidate），所以这里读到的 pending 反映的是
+// 上一次归纳之后的状态 —— 客户端据此显示「有 N 条待整理」已经够用。
+func runRequirements(cmd *cobra.Command, opts *askOptions) error {
+	where := strings.TrimSpace(opts.requirements)
+	listAll := where == "" || where == "all" || where == "*"
+
+	all, err := requirements.Workspaces()
+	if err != nil {
+		return fmt.Errorf("--requirements: 读取需求清单失败: %w", err)
+	}
+	out := struct {
+		OK         bool                     `json:"ok"`
+		Root       string                   `json:"root"`
+		Workspaces []requirements.Workspace `json:"workspaces"`
+	}{OK: true, Root: requirements.Root(), Workspaces: []requirements.Workspace{}}
+
+	if listAll {
+		out.Workspaces = all
+		return printJSON(cmd.OutOrStdout(), out)
+	}
+	// 按 id 或目录过滤：客户端手里通常只有目录，两种写法都认。
+	id := requirements.DirID(where)
+	for _, w := range all {
+		if w.ID == where || (id != "" && w.ID == id) || (w.Dir != "" && w.Dir == where) {
+			out.Workspaces = append(out.Workspaces, w)
+		}
+	}
+	if len(out.Workspaces) == 0 {
+		return fmt.Errorf("--requirements %s: 不认识这个工作区（既不是 ws id，也没有任何会话/文档过这个目录）", where)
+	}
+	return printJSON(cmd.OutOrStdout(), out)
+}
+
+// runConsolidateRequirements 立即归纳一轮：`--consolidate-requirements <ws_id|目录|.>`。
+//
+// `.` = 当前目录（与 `-w` 的默认语义一致：用户站在哪个项目里，整理的就是哪个项目）。
+func runConsolidateRequirements(cmd *cobra.Command, opts *askOptions) error {
+	where := strings.TrimSpace(opts.consolidateReqs)
+	if where == "." {
+		where = ""
+	}
+	timeout := opts.reqTimeout
+	if !flagChanged(cmd, "requirement-timeout") {
+		timeout = requirements.DefaultTimeout
+	}
+	res, err := requirements.Consolidate(cmd.Context(), where, requirements.Options{
+		Force:   opts.reqForce,
+		All:     opts.reqAll,
+		Engine:  opts.reqEngine,
+		Model:   opts.reqModel,
+		Timeout: timeout,
+		Auto:    opts.reqAuto,
+	})
+	// busy 不是错误：另一个进程正在归纳（客户端的防抖 + 用户手点撞上了），
+	// 这一轮跳过即可 —— 把它当失败会让界面弹一个没有意义的红字。
+	if err != nil && !requirements.IsBusy(err) {
+		if res.Error == "" {
+			res.Error = err.Error()
+		}
+		// 先输出结构化结果（客户端要能显示 last_error），再返回错误拿非零退出码。
+		_ = printJSON(cmd.OutOrStdout(), res)
+		return fmt.Errorf("--consolidate-requirements %s: %s", strings.TrimSpace(opts.consolidateReqs), err)
+	}
+	return printJSON(cmd.OutOrStdout(), res)
+}
+
+// bindRequirementFlags 注册需求聚合的 flags。
+//
+// --requirements / --consolidate-requirements 的值都可以留空（空串是合法输入：
+// 前者 = 列全部，后者 = 当前目录），所以派发用 flagChanged 判断，不看值。
+func bindRequirementFlags(cmd *cobra.Command, opts *askOptions) {
+	f := cmd.PersistentFlags()
+	f.StringVar(&opts.requirements, "requirements", "", "列出需求清单（工作区 → 模块 → 功能点，JSON：{ok,root,workspaces}）。值留空 = 列全部；给 ws id 或目录 = 只列那一个。只读，不调模型")
+	f.StringVar(&opts.consolidateReqs, "consolidate-requirements", "", "立即把会话记忆归纳成需求文档（会调模型）。值留空 = 当前目录；给 ws id 或目录 = 归纳那一个")
+	f.BoolVar(&opts.reqForce, "requirement-force", false, "配合 --consolidate-requirements：没有未归纳的记忆也跑一轮（手动「立即整理」）")
+	f.BoolVar(&opts.reqAll, "requirement-all", false, "配合 --consolidate-requirements：全量重放历史记忆（回填 / 滚动校正）。仍走增量合并，只增不减，不会推翻已有内容")
+	f.StringVar(&opts.reqEngine, "requirement-engine", "", "--consolidate-requirements 用哪个引擎（空 = 自动：首次初始化挑能读目录的引擎，增量归纳用 llm）；客户端应传自己的默认引擎")
+	f.StringVar(&opts.reqModel, "requirement-model", "", "配合 --consolidate-requirements：增量归纳用的模型（空 = 引擎默认；首次目录初始化始终用初始化引擎的默认模型）")
+	f.DurationVar(&opts.reqTimeout, "requirement-timeout", requirements.DefaultTimeout, "配合 --consolidate-requirements：单次模型调用超时（默认归纳 4m / 首次目录初始化 9m）")
+	f.BoolVar(&opts.reqAuto, "requirement-auto", false, "配合 --consolidate-requirements：自动归纳（不触发首次按目录初始化；插件轮末 / 每日兜底用）")
+}

package/internal/cli/requirements_test.go

@@ -0,0 +1,36 @@
+package cli
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/darren/magic-agent/internal/requirements"
+)
+
+// TestRequirementModifiersDispatchWithMainFlag 修饰 flag 与主 flag 同时出现时，
+// 必须先走「归纳」分支，而不是被修饰项的分支误判成「只给了修饰项」。
+//
+// 2026-10-22 实测：`--consolidate-requirements <dir> --requirement-force` 直接
+// exit 2（报「只在 --consolidate-requirements 下成立」）—— 手机端点「整理」时
+// 带 force 就是这条路径。用例只断言错误**不是**那句误判；目录不存在时真正的错误
+// 应该是「工作区不存在」。
+func TestRequirementModifiersDispatchWithMainFlag(t *testing.T) {
+	t.Setenv(requirements.EnvDir, t.TempDir())
+	missing := filepath.Join(t.TempDir(), "not-a-workspace")
+	_, _, err := runAskCmd(t, "", "--consolidate-requirements", missing, "--requirement-force")
+	if err == nil {
+		t.Fatal("不存在的目录应该报错（说明真的走到了归纳分支）")
+	}
+	if strings.Contains(err.Error(), "只在 --consolidate-requirements 下成立") {
+		t.Fatalf("主 flag + 修饰 flag 被误判成只有修饰 flag：%v", err)
+	}
+}
+
+// TestRequirementModifierAloneStillFails 单给修饰项仍然要明确报错（不静默忽略）。
+func TestRequirementModifierAloneStillFails(t *testing.T) {
+	_, _, err := runAskCmd(t, "", "--requirement-force")
+	if err == nil || !strings.Contains(err.Error(), "只在 --consolidate-requirements 下成立") {
+		t.Fatalf("单给 --requirement-force 应明确报错，实际 %v", err)
+	}
+}

package/internal/cli/root.go

@@ -78,6 +78,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/darren/magic-agent/internal/agent"
+	"github.com/darren/magic-agent/internal/team"
 )
 
 // Version 版本号。
@@ -386,6 +387,26 @@ codebuddy-gateway 引擎（CodeBuddy Code HTTP 网关，走 webhook + SSE；凭
   session_id 到手后改名为 <session_id>.jsonl（读侧两个名字都认）——
   于是「正在跑的会话」在别的客户端里当场可读，引擎整轮不给 id 的形态也不白开存档。
 
+需求聚合（--requirements / --consolidate-requirements）：
+  把**会话里聊过的需求**自动归纳成功能点文档（两级：模块 → 功能点）。口径与「会话标题」
+  同源：只留一份实现，PC / 移动端 / 直接跑 CLI 的会话一视同仁（无论谁发起的都算）。
+    magic-agent --requirements all                    # 列全部工作区（只读，不调模型）
+    magic-agent --requirements ~/work/proj             # 只列这个目录（也认 ws id）
+    magic-agent --consolidate-requirements ~/work/proj # 手动整理一轮（**会调模型**）
+    magic-agent --consolidate-requirements . --requirement-force   # 没有新记忆也跑一轮
+    magic-agent --consolidate-requirements . --requirement-all     # 全量重放（回填 / 校正）
+  第一次整理 = 初始化：state 里没有 bootstrap_at 时，先按**空间目录**反推一版需求基线
+  （有界扫描 + 带工具的引擎读代码，自动选 claude/codebuddy/codex/dsh 等能读目录的引擎），
+  并把此前旧会话记为已消费；之后只处理上次游标之后的新会话（没有新会话就 noop）。
+  目录为空不是错误（回落到会话增量）。插件的自动归纳带 --requirement-auto，只做增量、
+  绝不触发初始化 —— 否则每轮对话都可能悄悄花几分钟读代码。
+  记忆来源是 core 自己的会话日志（kind:"user"），会话按「-w 指定的 workspace，没有则它跑的
+  当前目录」归到工作区。存储 ~/.magic-agent/requirements/（MAGIC_AGENT_REQUIREMENTS 可覆盖），
+  每个功能点一篇 markdown（features/<模块>/<名称>.md），可直接用访达打开。
+  归纳是**增量的、只增不减**：模型只给 desc / 需求点 / 结论 / 来源编号，骨架与日期由代码写；
+  已有文档的模块不搬家（模型每轮的 module 会漂）。
+  ⚠️ 读清单绝不触发归纳 —— 只有 --consolidate-requirements（或插件的轮末防抖）才调模型。
+
 附件（-a/--attach：文件＋提示词，比如截图加提示词）：
   每个引擎尽量用**自己的原生方式**收附件，能力见 --engines 的 attachments 字段：
     codex      flag:-i            原生 -i/--image（图片；resume 轮退化为提示词里的路径）
@@ -467,6 +488,23 @@ codebuddy-gateway 引擎（CodeBuddy Code HTTP 网关，走 webhook + SSE；凭
 			case flagChanged(cmd, "before"), flagChanged(cmd, "limit"):
 				// 同上：--before / --limit 是 --session-log 的翻页参数，单给必然是误解。
 				return &usageError{fmt.Errorf("--before / --limit 只在 --session-log 下成立：请配合 --session-log <id> 使用")}
+			/* ⚠️ 主 flag 必须排在修饰 flag 之前：下面那串 --requirement-* 是
+			   --consolidate-requirements 的修饰项，但它们在命令行上**同时出现**时也各自
+			   Changed=true。先判修饰项会把「主 flag + force」误判成「只给了 force」，
+			   调用方带 force 手动整理时直接 exit 2（2026-10-22 修）。 */
+			case flagChanged(cmd, "requirements"):
+				// 读清单：值留空 = 列全部工作区（`--requirements ""` 也是合法调用）。
+				return runRequirements(cmd, opts)
+			case flagChanged(cmd, "consolidate-requirements"):
+				// 写：跑一轮归纳。值留空 = 当前目录。
+				return runConsolidateRequirements(cmd, opts)
+			case flagChanged(cmd, "requirement-force"), flagChanged(cmd, "requirement-all"),
+				flagChanged(cmd, "requirement-engine"), flagChanged(cmd, "requirement-model"),
+				flagChanged(cmd, "requirement-timeout"), flagChanged(cmd, "requirement-auto"):
+				// 这些只修饰「归纳」这一轮。单给它们必然是调用方想归纳却写漏了主 flag ——
+				// 静默忽略就等于「传了参数什么都没发生」。
+				return &usageError{fmt.Errorf("--requirement-force / -all / -engine / -model / -timeout / -auto " +
+					"只在 --consolidate-requirements 下成立：请配合它使用")}
 			case flagChanged(cmd, "stop"):
 				// 用「传过没有」而不是「值非空」判断：`--stop ""` 也要走参数校验
 				//（exit 2 提示要 id），而不是掉进「提问」分支报 empty prompt。
@@ -480,6 +518,10 @@ codebuddy-gateway 引擎（CodeBuddy Code HTTP 网关，走 webhook + SSE；凭
 				return runContract(cmd, opts)
 			case opts.engines:
 				return runEngines(cmd, opts)
+			case opts.team:
+				// 团队模式必须排在 --stream 之前：它自己就是流式路径的一种运行模式
+				//（同一套 ready / seq / result 收尾），但内部编排完全不同。
+				return runTeamAsk(cmd, args, opts)
 			case opts.stream:
 				return runStreamAsk(cmd, args, opts)
 			}
@@ -908,8 +950,18 @@ func emitEngineRows(cmd *cobra.Command, opts *askOptions, envelope bool) error {
 	/* 匿名结构体就地引用函数内的 row 类型：不必把 row 提到包级，
 	   也就不会把上面那张字段注释表搬来搬去。 */
 	return printJSON(cmd.OutOrStdout(), struct {
-		ContractVersion int      `json:"contractVersion"`
-		Features        []string `json:"features"`
-		Engines         []row    `json:"engines"`
-	}{ContractVersion: agent.ContractVersion, Features: agent.CoreFeatures(), Engines: rows})
+		ContractVersion int `json:"contractVersion"`
+		// Version 本 CLI 的版本号（ldflags 从 package.json 注入 internal/cli.Version）。
+		// 新增（2026-10-22，只增字段不升 contractVersion）：客户端「我的」页要显示
+		// 当前连着的这份 magic-agent 是哪一版 —— 移动端界面是桌面端 `/m/` 远程加载的，
+		// 自己不带版本；core 的版本才是用户真正在跑的那一份。老 core 没有该字段 → 空串。
+		Version  string   `json:"version,omitempty"`
+		Features []string `json:"features"`
+		Engines  []row    `json:"engines"`
+		// TeamRoles 团队子任务的角色清单（name / kind / duty）。
+		// 新增（2026-10-22，只增字段不升 contractVersion）：客户端「团队模式」页
+		// 要按角色配置路由（`--team-route role:writer=…`），角色名不能由客户端硬编码 ——
+		// 老 core 没有这个字段，客户端回落到内置清单。
+		TeamRoles []team.RoleInfo `json:"teamRoles"`
+	}{ContractVersion: agent.ContractVersion, Version: Version, Features: agent.CoreFeatures(), Engines: rows, TeamRoles: team.RoleInfos()})
 }