magic-agent 2.4.3 → 2.6.3

package/internal/client/publicurl.go

@@ -0,0 +1,82 @@
+package client
+
+/* publicurl.go - 公网入口（cloudflared quick tunnel 域名）的**落盘**。
+ *
+ * 为什么（2026-10-25 用户：「重启也尽量不要变 cloudflare 域名就可以了」）：
+ * 隧道是壳（掌天瓶）起的，quick tunnel 的域名只在**隧道重起**时才会变；magic-client
+ * 重启根本不碰 cloudflared，域名本该原样不变。但域名探测结果以前只存在内存里 ——
+ * 客户端一重启就丢，`/desk/health` 头几次请求报 `publicUrl: ""`，手机于是退回局域网
+ * 地址：用户看到的就是「重启后地址变了」。
+ *
+ * 所以把探测到的域名落盘（profile 数据目录的 `public-url`），启动即读回当「上次已知」：
+ *   · 隧道没重起 → 域名正确，手机一条连接都不用改；
+ *   · 隧道真重起了 → 后台探测在 publicTTL 内换成新域名；
+ *   · cloudflared 比客户端起得慢 → 宽限期（publicGrace）内不采纳「探不到」，
+ *     已知域名先顶着，别在这一小段里把用户推到局域网地址上。
+ */
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+)
+
+// publicGrace 重启后的宽限期：这段时间里探测不到隧道也**不撤掉**已落盘的域名。
+//
+// 顺带解决的是「壳重启」这个场景：cloudflared 要几百毫秒到几秒才把 metrics 端口开起来，
+// 客户端如果抢在前面探空并清掉已知域名，手机就会在这段空窗里换地址。
+const publicGrace = 90 * time.Second
+
+// publicURLFile 落盘文件（与 instance-id 同目录：同一份 profile = 同一台桌面）。
+func publicURLFile(prof Profile) string {
+	dir := strings.TrimSpace(prof.DataDir())
+	if dir == "" {
+		return ""
+	}
+	return filepath.Join(dir, "public-url")
+}
+
+// loadSavedPublicURL 读上次落盘的域名；没有/读不出 → 空串。
+func (s *Service) loadSavedPublicURL() string {
+	p := publicURLFile(s.opts.Profile)
+	if p == "" {
+		return ""
+	}
+	b, err := os.ReadFile(p)
+	if err != nil {
+		return ""
+	}
+	u := strings.TrimSpace(string(b))
+	if !strings.HasPrefix(u, "https://") && !strings.HasPrefix(u, "http://") {
+		return "" // 半截写入 / 手改坏了：当作没有，别把垃圾地址发给手机
+	}
+	return strings.TrimRight(u, "/")
+}
+
+// savePublicURL 落盘当前域名（0600）。写不下不是致命错：本次仍能用，只是下次重启会重新探。
+func (s *Service) savePublicURL(u string) {
+	p := publicURLFile(s.opts.Profile)
+	if p == "" || strings.TrimSpace(u) == "" {
+		return
+	}
+	if err := os.MkdirAll(filepath.Dir(p), 0o700); err != nil {
+		return
+	}
+	_ = os.WriteFile(p, []byte(strings.TrimSpace(u)+"\n"), 0o600)
+}
+
+// clearSavedPublicURL 删掉落盘的域名（连续探测确认隧道真的没了）。
+func (s *Service) clearSavedPublicURL() {
+	p := publicURLFile(s.opts.Profile)
+	if p == "" {
+		return
+	}
+	_ = os.Remove(p)
+}
+
+// publicURLOrEmpty 供交接用：拿当前已知的公网域名（不触发等待）。
+func (s *Service) publicURLOrEmpty() string {
+	u := s.publicURL()
+	return strings.TrimRight(strings.TrimSpace(u), "/")
+}

package/internal/client/quotas_merge_test.go

@@ -0,0 +1,107 @@
+package client
+
+// quotas_merge_test.go - --quotas 现查结果合并进缓存的引擎清单（额度不跟着缓存冻住）。
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestMergeQuotaJSONOverridesStaleValues(t *testing.T) {
+	engines := []byte(`[
+		{"engine":"llm","ok":true,"credit_suffix":"%",
+		 "model_quota":{"MiniMax-M3.1-Flash":{"interval_left":"98","weekly_left":"53"},
+		                "minimax-peter":{"interval_left":"98","weekly_left":"53"}}},
+		{"engine":"codebuddy","ok":true,"credit_left":"5800.1","checkin_today":false,"checkin_credit":"100"},
+		{"engine":"trae","ok":true}
+	]`)
+	quotas := []byte(`[
+		{"engine":"llm","credit_suffix":"%",
+		 "model_quota":{"MiniMax-M3.1-Flash":{"interval_left":"98","weekly_left":"53"},
+		                "minimax-peter":{"interval_left":"1","weekly_left":"0"}}},
+		{"engine":"codebuddy","credit_left":"5910.77","checkin_today":true,"checkin_credit":"100"}
+	]`)
+
+	out := mergeQuotaJSON(engines, quotas)
+	var rows []map[string]any
+	if err := json.Unmarshal(out, &rows); err != nil {
+		t.Fatalf("合并结果不是合法 JSON: %v\n%s", err, out)
+	}
+	if len(rows) != 3 {
+		t.Fatalf("引擎行数变了: %d", len(rows))
+	}
+
+	byEngine := map[string]map[string]any{}
+	for _, r := range rows {
+		byEngine[r["engine"].(string)] = r
+	}
+	if got := byEngine["codebuddy"]["credit_left"]; got != "5910.77" {
+		t.Errorf("credit_left 未刷新: %v", got)
+	}
+	if got := byEngine["codebuddy"]["checkin_today"]; got != true {
+		t.Errorf("checkin_today 未刷新: %v", got)
+	}
+	quota := byEngine["llm"]["model_quota"].(map[string]any)
+	peter := quota["minimax-peter"].(map[string]any)
+	if peter["interval_left"] != "1" || peter["weekly_left"] != "0" {
+		t.Errorf("minimax-peter 额度未按新 key 刷新: %v", peter)
+	}
+	if _, ok := byEngine["trae"]["credit_left"]; ok {
+		t.Errorf("没有额度的引擎不该被塞字段: %v", byEngine["trae"])
+	}
+}
+
+func TestMergeQuotaJSONKeepsOldOnEmpty(t *testing.T) {
+	engines := []byte(`[{"engine":"codebuddy","ok":true,"credit_left":"5800.1"}]`)
+	// 现查失败（字段缺失 / 空串）时保留缓存里的旧值，不能把数字抹掉。
+	quotas := []byte(`[{"engine":"codebuddy","credit_left":""}]`)
+
+	out := mergeQuotaJSON(engines, quotas)
+	var rows []map[string]any
+	if err := json.Unmarshal(out, &rows); err != nil {
+		t.Fatal(err)
+	}
+	if got := rows[0]["credit_left"]; got != "5800.1" {
+		t.Fatalf("空结果覆盖了旧值: %v", got)
+	}
+}
+
+func TestMergeQuotaJSONBadInputFallsBack(t *testing.T) {
+	engines := []byte(`[{"engine":"llm","ok":true}]`)
+	if out := mergeQuotaJSON(engines, []byte("not json")); string(out) != string(engines) {
+		t.Fatalf("额度输出非法时应原样返回，实际 %s", out)
+	}
+}
+
+// 登录态也要现查：缓存里是「已登录」，但用户刚登出时下一次打开就该隐藏。
+func TestMergeQuotaJSONLoggedIn(t *testing.T) {
+	engines := []byte(`[
+		{"engine":"codebuddy","ok":true,"logged_in":true,"account":"旧昵称"},
+		{"engine":"codebuddy-ai","ok":true,"logged_in":true}
+	]`)
+	quotas := []byte(`[
+		{"engine":"codebuddy","logged_in":true,"account":"Darren"},
+		{"engine":"codebuddy-ai","logged_in":false}
+	]`)
+
+	out := mergeQuotaJSON(engines, quotas)
+	var rows []map[string]any
+	if err := json.Unmarshal(out, &rows); err != nil {
+		t.Fatal(err)
+	}
+	got := map[string]any{}
+	acct := map[string]any{}
+	for _, r := range rows {
+		got[r["engine"].(string)] = r["logged_in"]
+		acct[r["engine"].(string)] = r["account"]
+	}
+	if got["codebuddy"] != true {
+		t.Errorf("codebuddy logged_in = %v, want true", got["codebuddy"])
+	}
+	if got["codebuddy-ai"] != false {
+		t.Errorf("codebuddy-ai 登出后应合并为 false，实际 %v", got["codebuddy-ai"])
+	}
+	if acct["codebuddy"] != "Darren" {
+		t.Errorf("账号昵称未刷新: %v", acct["codebuddy"])
+	}
+}

package/internal/client/requirements.go

@@ -28,14 +28,17 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"net/url"
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"sync"
 	"time"
 
 	"github.com/darren/magic-agent/internal/agent"
+	"github.com/darren/magic-agent/internal/requirements"
 )
 
 // FeatureRequirements core 侧的能力位（与 internal/agent 的同名常量一致）。
@@ -45,6 +48,12 @@ import (
 // 「插件依赖哪些能力位」在 grep 时只有一处 —— 与 FeatureSessionTeam 的处理方式一致。
 const FeatureRequirements = "feature.requirements"
 
+// FeatureRequirementShots core 侧的能力位（与 internal/agent 的同名常量一致）。
+//
+// 与 FeatureRequirements 分开：core 可能支持需求聚合但还不支持截图 ——
+// 界面要能分别判断，别把「需求」页签整个藏掉。
+const FeatureRequirementShots = "feature.requirement.shots"
+
 // reqAutoDebounce 一轮收尾后等多久再归纳（期间再来一轮就顺延）。
 const reqAutoDebounce = 12 * time.Second
 
@@ -54,6 +63,12 @@ const reqAutoDebounce = 12 * time.Second
 // core 侧单次调用默认 4 分钟。给到 10 分钟覆盖「首次回填一大段历史」这种最慢的情况。
 const reqConsolidateTimeout = 10 * time.Minute
 
+// reqShotTimeout 追加截图的上限。
+//
+// 落盘本身是毫秒级的，但要先抢 core 的归纳锁（另一轮归纳在跑时要等）——
+// 给 30 秒足够，又不至于让界面一直转圈。
+const reqShotTimeout = 30 * time.Second
+
 // reqAutoOffEnv 关掉自动归纳的环境变量（排查 / 省额度用）。
 const reqAutoOffEnv = "MAGIC_CLIENT_NO_REQ_AUTO"
 
@@ -80,6 +95,25 @@ func (s *Service) handleRequirements(w http.ResponseWriter, r *http.Request) {
 	s.proxyCore(w, r, "--requirements", ws)
 }
 
+// handleRequirementsGraph GET /desk/requirements/graph?ws=<ws_id|目录>：
+// 会话↔需求关系图谱（nodes=会话/功能点，edges=关系）。纯读转发，同族范式。
+func (s *Service) handleRequirementsGraph(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		writeErr(w, http.StatusMethodNotAllowed, "GET only")
+		return
+	}
+	if !hasStr(s.contract.Features, FeatureRequirements) {
+		writeErr(w, http.StatusNotImplemented,
+			"当前 core 不支持需求聚合（缺少 "+FeatureRequirements+" 能力位，请升级 magic-agent）")
+		return
+	}
+	ws := strings.TrimSpace(r.URL.Query().Get("ws"))
+	if ws == "" {
+		ws = "all"
+	}
+	s.proxyCore(w, r, "--requirements-graph", ws)
+}
+
 // handleRequirementsConsolidate POST /desk/requirements/consolidate：
 // 立即归纳一轮（用户点「整理」）。
 //
@@ -149,6 +183,156 @@ func (s *Service) handleRequirementsConsolidate(w http.ResponseWriter, r *http.R
 	writeCoreJSON(w, out)
 }
 
+// handleRequirementsShots POST /desk/requirements/shots：
+// 给一个功能点追加一张「页面完成情况」截图。
+//
+// 请求体 = **PNG 原始字节**（不是 multipart）：这条通道只收图，形状越简单越不容易出错。
+// 参数走查询串：ws（工作区 id 或目录，空 = 当前目录）、module、name（功能点名）、caption。
+//
+// 为什么图片不直接落到需求目录、而要过 core：
+//
+//	需求文档是 core 的资产（~/.magic-agent/requirements/<wsid>/），它有自己的一套
+//	锁（与归纳共用）、路径归一（Windows 反斜杠）与文档段落格式。让 core 来写，
+//	客户端就只负责「拿到字节、传过去」—— 两边不会各写一套格式。
+func (s *Service) handleRequirementsShots(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "POST only")
+		return
+	}
+	/* 能力位 gate：老 core 没有 --requirement-shot（exit 2）。先查能力位并**说清楚为什么** ——
+	   让用户看到「core 太旧，请升级」，比让它报一句 usage error 强得多。 */
+	if !hasStr(s.contract.Features, FeatureRequirementShots) {
+		writeErr(w, http.StatusNotImplemented,
+			"当前 core 不支持需求截图（缺少 "+FeatureRequirementShots+" 能力位，请升级 magic-agent）")
+		return
+	}
+	q := r.URL.Query()
+	name := strings.TrimSpace(q.Get("name"))
+	if name == "" {
+		writeErr(w, http.StatusBadRequest, "缺少 name（功能点名）")
+		return
+	}
+	module := strings.TrimSpace(q.Get("module"))
+	caption := strings.TrimSpace(q.Get("caption"))
+	ws := strings.TrimSpace(q.Get("ws"))
+	if ws == "" {
+		if wd, err := os.Getwd(); err == nil {
+			ws = wd
+		}
+	}
+	if ws == "" {
+		writeErr(w, http.StatusBadRequest, "ws 不能为空")
+		return
+	}
+	// 先收进内存再判大小。
+	//
+	// ⚠️ 不用 http.MaxBytesReader：它一超限就直接写 400（"request body too large"），
+	// 分不清「图片太大」和「请求体坏了」—— 用户看到的是一句看不懂的错。
+	// 这里自己读，超限的单独回 413。
+	body, err := io.ReadAll(io.LimitReader(r.Body, requirements.MaxShotBytes+1))
+	if err != nil {
+		writeErr(w, http.StatusBadRequest, "读取截图失败："+err.Error())
+		return
+	}
+	if len(body) == 0 {
+		writeErr(w, http.StatusBadRequest, "截图内容为空")
+		return
+	}
+	if len(body) > requirements.MaxShotBytes {
+		writeErr(w, http.StatusRequestEntityTooLarge,
+			fmt.Sprintf("截图过大（上限 %d 字节）", requirements.MaxShotBytes))
+		return
+	}
+	args := []string{"--requirement-shot", ws, "--requirement-name", name}
+	if module != "" {
+		args = append(args, "--requirement-module", module)
+	}
+	if caption != "" {
+		args = append(args, "--requirement-caption", caption)
+	}
+	out, err := s.runCoreTimedStdin(r.Context(), reqShotTimeout, bytes.NewReader(body), args...)
+	if err != nil {
+		code := http.StatusBadGateway
+		if isCoreTimeout(err) {
+			code = http.StatusGatewayTimeout
+		}
+		writeErr(w, code, fmt.Sprintf("%s --requirement-shot 失败：%v", s.opts.MagicAgent, err))
+		return
+	}
+	writeCoreJSON(w, out)
+}
+
+// handleRequirementShotRemote POST /desk/requirements/shot-remote：
+// 服务端 agent-browser 打开 url 截一张全页图，落到 /desk/uploads/ 并回图片地址。
+//
+// 2026-10-25 内置浏览器 MCP 改基 agent-browser 后，手机端的「截图」不再依赖
+// 页面内 relay 的 html2canvas（跨域污染 / iframe 抓不到 / 慢页超时），改由
+// 服务端真实 Chromium 截图。请求体 JSON：{"url":"…"}（必须 http/https）。
+// 响应：{ok, data:"/desk/uploads/…png"}（data 直接喂给标注浮层的 <img>）。
+//
+// 能力位与 /desk/requirements/shots 同一杆秤：缺 feature.requirement.shots 回 501；
+// 服务端没装 agent-browser 也回 501 + 安装提示。
+func (s *Service) handleRequirementShotRemote(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeErr(w, http.StatusMethodNotAllowed, "POST only")
+		return
+	}
+	if !hasStr(s.contract.Features, FeatureRequirementShots) {
+		writeErr(w, http.StatusNotImplemented,
+			"当前 core 不支持需求截图（缺少 "+FeatureRequirementShots+" 能力位，请升级 magic-agent）")
+		return
+	}
+	var req struct {
+		URL      string `json:"url"`
+		FullPage bool   `json:"full_page,omitempty"`
+	}
+	body, err := io.ReadAll(io.LimitReader(r.Body, 64<<10))
+	if err != nil {
+		writeErr(w, http.StatusBadRequest, "读取请求失败："+err.Error())
+		return
+	}
+	if err := json.Unmarshal(body, &req); err != nil {
+		writeErr(w, http.StatusBadRequest, "请求体不是合法 JSON")
+		return
+	}
+	u := strings.TrimSpace(req.URL)
+	if !strings.HasPrefix(u, "http://") && !strings.HasPrefix(u, "https://") {
+		writeErr(w, http.StatusBadRequest, "url 必须是 http/https 地址")
+		return
+	}
+	if abBin() == "" {
+		writeErr(w, http.StatusNotImplemented,
+			"服务端未安装 agent-browser（npm install -g agent-browser && agent-browser install，或设 "+EnvAgentBrowserBin+"）")
+		return
+	}
+	// 截图落 uploads 目录（与 /desk/upload 同一个家，/desk/uploads/<name> 可回读）。
+	dir := filepath.Join(os.TempDir(), "magic-client-uploads")
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		writeErr(w, http.StatusInternalServerError, "创建上传目录失败："+err.Error())
+		return
+	}
+	out := filepath.Join(dir, strconv.FormatInt(time.Now().UnixNano(), 10)+"-reqshot.png")
+	if err := abOpen(r.Context(), u); err != nil {
+		writeErr(w, http.StatusBadGateway, "agent-browser 打开页面失败："+err.Error())
+		return
+	}
+	if err := abShot(r.Context(), out, req.FullPage); err != nil {
+		_ = os.Remove(out)
+		writeErr(w, http.StatusBadGateway, "agent-browser 截图失败："+err.Error())
+		return
+	}
+	st, err := os.Stat(out)
+	if err != nil || st.Size() == 0 {
+		writeErr(w, http.StatusBadGateway, "截图文件没有生成")
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{
+		"ok":   true,
+		"data": "/desk/uploads/" + url.PathEscape(filepath.Base(out)),
+		"size": st.Size(),
+	})
+}
+
 // consolidateArgs 组归纳命令。
 //
 // engine/model 来自客户端配置的默认引擎（手动「整理」）：传了就用它，core 不再自动换。
@@ -180,9 +364,19 @@ func consolidateArgs(ws, module string, force, all, auto bool, engine, model str
 
 // runCoreTimed 与 runCore 同形，但超时可调（归纳不是 45s 能跑完的）。
 func (s *Service) runCoreTimed(ctx context.Context, timeout time.Duration, args ...string) ([]byte, error) {
+	return s.runCoreTimedStdin(ctx, timeout, nil, args...)
+}
+
+// runCoreTimedStdin 与 runCoreTimed 同形，但把 stdin 接到子进程。
+//
+// 截图走这条路：PNG 几百 KB，放进 argv 会撞命令行长度上限、也会把二进制搅进进程列表。
+func (s *Service) runCoreTimedStdin(ctx context.Context, timeout time.Duration, stdin io.Reader, args ...string) ([]byte, error) {
 	ctx, cancel := context.WithTimeout(ctx, timeout)
 	defer cancel()
-	cmd := exec.CommandContext(ctx, s.opts.MagicAgent, args...)
+	cmd := newCoreCmd(ctx, s.opts.MagicAgent, args...)
+	if stdin != nil {
+		cmd.Stdin = stdin
+	}
 	// 与 runCore 同一道保险：core 的后代进程握着管道时 Wait 不能永久挂住。
 	cmd.WaitDelay = 5 * time.Second
 	var stdout, stderr bytes.Buffer
@@ -288,9 +482,17 @@ func (s *Service) runAutoConsolidate(ws string) {
 	s.reqAuto.running[ws] = true
 	s.reqAuto.mu.Unlock()
 
+	/* 引擎/模型：**与手动「整理」同一口径** —— 「整理的引擎就是配置的默认引擎」。
+	   后台没有请求体可带，于是从唯一的权威配置源（/desk/prefs 落的那份 JSON）读；
+	   读不到（还没配过 / 文件坏了）= 传空，core 仍按自己的默认（llm）跑，与旧行为一致。 */
+	engine, model := s.defaultEngineModel()
+	if engine != "" {
+		s.logf("需求自动归纳 %s: 引擎 %s%s", ws, engine, modelSuffix(model))
+	}
+
 	// 归纳是后台行为：**不绑**任何 HTTP 请求的生命周期，用独立 context。
 	ctx, cancel := context.WithTimeout(context.Background(), reqConsolidateTimeout)
-	out, err := s.runCoreTimed(ctx, reqConsolidateTimeout, consolidateArgs(ws, "", false, false, true, "", "")...)
+	out, err := s.runCoreTimed(ctx, reqConsolidateTimeout, consolidateArgs(ws, "", false, false, true, engine, model)...)
 	cancel()
 	if err != nil {
 		s.log.Printf("需求自动归纳失败 %s: %v", ws, err)
@@ -327,3 +529,6 @@ func (s *Service) runAutoConsolidate(ws string) {
 
 // 编译期断言：能力位常量与 core 侧同值（改错一个字这里就编译不过）。
 var _ = func() bool { return agent.FeatureRequirements == FeatureRequirements }
+
+// 同上，截图能力位。
+var _ = func() bool { return agent.FeatureRequirementShots == FeatureRequirementShots }

package/internal/client/requirements_shots_test.go

@@ -0,0 +1,200 @@
+package client
+
+// requirements_shots_test.go - 「页面完成情况」截图端点的三条硬约束：
+//   · 老 core 缺能力位 → 501 且点名缺哪个位（不是 400/502 让人猜）；
+//   · PNG 走 **stdin** 传给 core（不进 argv：几百 KB 会撞命令行长度上限）；
+//   · 参数（ws / module / name / caption）原样透传。
+//
+// 假 core 用 .bat（Windows 上 exec 不了 shebang 脚本 —— 既有基线，见 jobs_test.go）。
+
+import (
+	"bytes"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+// shotCore 假 core：回契约、记下参数、并把从 stdin 收到的字节长度写进日志。
+//
+// ⚠️ Windows 上的两个坑（都只影响**测试桩**，真实 core 是 .exe，直接 exec 时
+// 中文参数与二进制 stdin 都是完好的 —— 实测 arg[2]="需求页" 字节 e9 9c 80…）：
+//   ① cmd.exe 按**控制台代码页**（936=GBK）传参，桩里要按同一编码解读；
+//   ② PNG 头里有 0x1A（EOF 字符），文本模式读 stdin 会**截断**（12 字节只读到 11）——
+//      必须用二进制模式读。
+//
+// 二进制读 stdin 的写法踩过坑：[Console]::OpenStandardInput() 返回的是 Stream，
+// **没有 ReadToEnd**（PowerShell 5.1 会报 method not found，$b 保持 null → 记成 0 字节）。
+// 正确写法是 CopyTo 到 MemoryStream 再看 Length。
+func shotCore(t *testing.T, features, logPath string) string {
+	t.Helper()
+	dir := t.TempDir()
+	if runtime.GOOS == "windows" {
+		// 读 stdin 的小脚本单独放一个 .ps1：批处理里的 -Command 引号嵌套太容易走样。
+		ps1 := filepath.Join(dir, "readstdin.ps1")
+		psBody := "$stdin = [Console]::OpenStandardInput()\n" +
+			"$ms = New-Object System.IO.MemoryStream\n" +
+			"$stdin.CopyTo($ms)\n" +
+			"[Console]::Out.Write('STDIN_BYTES=' + $ms.Length + \"`n\")\n"
+		if err := os.WriteFile(ps1, []byte(psBody), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		path := filepath.Join(dir, "magic-agent.bat")
+		lines := []string{
+			`@echo off`,
+			`set "A=%*"`,
+			`echo %A%>>"` + logPath + `"`,
+			`if "%A:--contract=%" == "%A%" goto other`,
+			`echo {"contractVersion":2,"features":[` + features + `],"engines":[]}`,
+			`exit /b 0`,
+			`:other`,
+			// 二进制读 stdin，记下字节数（追加进同一个日志）。
+			`powershell -NoProfile -ExecutionPolicy Bypass -File "` + ps1 + `">>"` + logPath + `"`,
+			`echo {"ok":true,"workspace":"ws-1","dir":"/x","file":"/x/f.md","path":"/x/1.png","shots":1}`,
+			`exit /b 0`,
+		}
+		// 批处理按代码页存（cmd.exe 按它解释脚本里的字节）。
+		body := strings.Join(lines, "\r\n") + "\r\n"
+		if err := os.WriteFile(path, encodeWindowsScript(body), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		return path
+	}
+	path := filepath.Join(dir, "magic-agent")
+	script := `#!/bin/sh
+echo "$*" >> ` + logPath + `
+case "$*" in
+  *--contract*)
+    echo '{"contractVersion":2,"features":[` + features + `],"engines":[]}'
+    exit 0
+    ;;
+esac
+# stdin 字节数（证明 PNG 走了 stdin）
+n=$(wc -c)
+echo "STDIN_BYTES=$n" >> ` + logPath + `
+echo '{"ok":true,"workspace":"ws-1","dir":"/x","file":"/x/f.md","path":"/x/1.png","shots":1}'
+exit 0
+`
+	if err := os.WriteFile(path, []byte(script), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}
+
+// shotsService 造一个带截图能力位的测试服务。
+func shotsService(t *testing.T, logPath string) *Service {
+	t.Helper()
+	core := shotCore(t, `"feature.session.events","feature.session.control",`+
+		`"`+FeatureRequirements+`","`+FeatureRequirementShots+`"`, logPath)
+	return newTestService(t, core)
+}
+
+func TestRequirementShotsRouteNeedsFeature(t *testing.T) {
+	logPath := filepath.Join(t.TempDir(), "calls.log")
+	core := shotCore(t, `"feature.session.events","feature.session.control"`, logPath)
+	svc := newTestService(t, core)
+
+	req := httptest.NewRequest(http.MethodPost, "/desk/requirements/shots?token=tok&name=需求页", bytes.NewReader([]byte("x")))
+	rec := httptest.NewRecorder()
+	svc.Handler().ServeHTTP(rec, req)
+	if rec.Code != http.StatusNotImplemented {
+		t.Fatalf("缺能力位应回 501，实际 %d: %s", rec.Code, rec.Body.String())
+	}
+	if !strings.Contains(rec.Body.String(), FeatureRequirementShots) {
+		t.Errorf("报错应点名缺哪个能力位，实际 %s", rec.Body.String())
+	}
+	for _, c := range readCalls(t, logPath) {
+		if strings.Contains(c, "--requirement-shot") {
+			t.Errorf("缺能力位时不该去调 core：%s", c)
+		}
+	}
+}
+
+func TestRequirementShotsRouteForwardsArgsAndStdin(t *testing.T) {
+	logPath := filepath.Join(t.TempDir(), "calls.log")
+	svc := shotsService(t, logPath)
+
+	png := []byte{0x89, 'P', 'N', 'G', 0x0D, 0x0A, 0x1A, 0x0A, 0x01, 0x02, 0x03, 0x04}
+	url := "/desk/requirements/shots?token=tok&ws=ws-1&module=%E4%BB%BB%E5%8A%A1%E5%88%97%E8%A1%A8&name=%E9%9C%80%E6%B1%82%E9%A1%B5&caption=%E6%94%B9%E6%88%90%E5%8F%8C%E5%88%97"
+	req := httptest.NewRequest(http.MethodPost, url, bytes.NewReader(png))
+	rec := httptest.NewRecorder()
+	svc.Handler().ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("截图应 200，实际 %d: %s", rec.Code, rec.Body.String())
+	}
+	// 响应是 core 的结构化结果。
+	if !strings.Contains(rec.Body.String(), `"ok":true`) {
+		t.Errorf("应原样回传 core 的结果，实际 %s", rec.Body.String())
+	}
+	var sawArgs bool
+	var sawStdin bool
+	for _, c := range readCalls(t, logPath) {
+		// ⚠️ Windows 上 cmd.exe 按控制台代码页传参 → 日志里是 GBK 字节。
+		// 按同一编码解读（真实 core 是 .exe，直接 exec 时参数是 UTF-8 —— 那是另一条路）。
+		decoded := decodeScriptBytes([]byte(c))
+		if strings.Contains(decoded, "--requirement-shot ws-1") &&
+			strings.Contains(decoded, "--requirement-name 需求页") &&
+			strings.Contains(decoded, "--requirement-module 任务列表") &&
+			strings.Contains(decoded, "--requirement-caption 改成双列") {
+			sawArgs = true
+		}
+		if strings.Contains(c, "STDIN_BYTES=") {
+			// PNG 字节数（12）应原样过 stdin。
+			if !strings.Contains(c, "STDIN_BYTES=12") {
+				t.Errorf("PNG 应原样走 stdin（12 字节），实际 %s", c)
+			}
+			sawStdin = true
+		}
+	}
+	if !sawArgs {
+		t.Errorf("参数应原样透传，实际 %v", readCalls(t, logPath))
+	}
+	if !sawStdin {
+		t.Errorf("PNG 应走 stdin 而不是 argv，实际 %v", readCalls(t, logPath))
+	}
+}
+
+func TestRequirementShotsRejectsBadInput(t *testing.T) {
+	logPath := filepath.Join(t.TempDir(), "calls.log")
+	svc := shotsService(t, logPath)
+	cases := []struct {
+		name string
+		url  string
+		body []byte
+		code int
+	}{
+		{"缺 name", "/desk/requirements/shots?token=tok", []byte("x"), http.StatusBadRequest},
+		{"空 body", "/desk/requirements/shots?token=tok&name=x", nil, http.StatusBadRequest},
+		{"GET 不行", "/desk/requirements/shots?token=tok&name=x", nil, http.StatusMethodNotAllowed},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			var req *http.Request
+			if c.code == http.StatusMethodNotAllowed {
+				req = httptest.NewRequest(http.MethodGet, c.url, nil)
+			} else {
+				req = httptest.NewRequest(http.MethodPost, c.url, bytes.NewReader(c.body))
+			}
+			rec := httptest.NewRecorder()
+			svc.Handler().ServeHTTP(rec, req)
+			if rec.Code != c.code {
+				t.Errorf("应回 %d，实际 %d: %s", c.code, rec.Code, rec.Body.String())
+			}
+		})
+	}
+}
+
+func TestRequirementShotsRejectsOversize(t *testing.T) {
+	logPath := filepath.Join(t.TempDir(), "calls.log")
+	svc := shotsService(t, logPath)
+	big := make([]byte, 9<<20) // > 8MB 上限
+	req := httptest.NewRequest(http.MethodPost, "/desk/requirements/shots?token=tok&name=x", bytes.NewReader(big))
+	rec := httptest.NewRecorder()
+	svc.Handler().ServeHTTP(rec, req)
+	if rec.Code != http.StatusRequestEntityTooLarge {
+		t.Errorf("超限应回 413，实际 %d: %s", rec.Code, rec.Body.String())
+	}
+}