@rover-studio/answer-me 0.1.0-rc.1

package/distribution/npm/skills/answerme/references/result-token-store.md

@@ -0,0 +1,50 @@
+# Result Token Store 契约
+
+## 目标
+
+Result Token Store 为 AnswerMe 提供跨进程、跨任务的结果凭证恢复能力。核心 Skill 只依赖本契约，不依赖某个操作系统的加密 API。
+
+## 必需操作
+
+每个平台适配器必须提供以下行为：
+
+| 操作 | 输入 | 结果 |
+|---|---|---|
+| `Validate` | 无，或受控测试根目录 | 验证当前身份能够加密、保存、回读并精确删除测试记录 |
+| `Save` | `interactionId`、Result Token | 原子保存并回读验证；同一 Token 可幂等重放，不同 Token 必须冲突失败 |
+| `Load` | `interactionId` | 仅向当前进程返回明文工作副本，不写入输出、日志或命令参数 |
+| `Delete` | `interactionId` | 只删除该交互的精确记录；不存在时安全返回未删除 |
+
+## 安全不变量
+
+- Result Token 不得写入仓库、Skill、聊天、命令参数、普通日志、Trace 或明文文件。
+- 进程内存和环境变量只能保存工作副本，不能作为唯一副本。
+- 存储键必须由 `interactionId` 安全派生，不能把未校验输入直接拼入文件路径。
+- `Save` 成功必须同时满足：持久化完成、当前身份回读成功、回读值与原值一致。
+- `pending`、等待超时、断网、空结果、进程退出、任务中断和 Result API 404 均不得触发删除。
+- 只有终态结果已经成功映射回原任务，或用户明确放弃恢复并授权删除时，才能调用 `Delete`。
+- 缺少可用适配器、验证失败或保存失败时必须失败关闭；不得交付 Answer URL，也不得重复创建替代交互。
+
+## 平台适配
+
+| 平台 | 推荐实现 | 当前状态 |
+|---|---|---|
+| Windows | 当前 Windows 用户保护的 DPAPI 或系统凭证库 | 已提供 DPAPI adapter |
+| macOS | Keychain | 未提供 adapter，必须失败关闭 |
+| Linux 桌面 | Secret Service / libsecret | 未提供 adapter，必须失败关闭 |
+| CI、容器、远程 Agent | 宿主 Secret Store 或 KMS | 未提供 adapter，必须失败关闭 |
+
+适配器只解决本机或宿主范围内的任务恢复。跨主机恢复需要共享 Secret Store，或由 AnswerMe 服务提供独立的安全凭证恢复协议。
+
+## Windows adapter
+
+当前实现位于 `scripts/result-token-store.windows.ps1`：
+
+- 默认目录：`%LOCALAPPDATA%\AnswerMe\result-token-credentials`；
+- 使用当前 Windows 账号的 DPAPI 加密 `PSCredential`；
+- 文件名使用 `SHA-256(interactionId)`，不直接使用外部输入；
+- CLIXML 的 `UserName` 也只保存固定前缀与 `SHA-256(interactionId)`，不得明文保存原始 `interactionId`；
+- 先写临时加密记录并回读验证，再原子移动到最终路径；
+- 非默认目录只允许隔离测试显式开启。
+
+`scripts/create-answerme.ps1` 在联网创建前验证 Store，创建成功后先持久化并回读，再返回不含 Result Token 的交付结果。`scripts/wait-answerme-result.ps1` 只从受保护 Store 恢复 Token；进程环境变量若存在，必须与受保护副本一致。完成终态结果映射后，调用 `scripts/remove-answerme-result-token.ps1` 精确清理凭证。

package/distribution/npm/skills/answerme/references/templates.md

@@ -0,0 +1,139 @@
+# AnswerMe 问卷模板规格
+
+## 校验总则
+
+创建脚本在任何网络请求前严格校验紧凑输入和完整模板；本文件是字段、类型、范围、唯一性与 Unicode 码点规则的唯一权威。JSON 必须解析为对象，根、题目、选项和 `visual` 对象均拒绝未知字段；字段值不得靠字符串转换“修正”成另一种类型。
+
+除 `body` 外，校验和存储前去除定义文本首尾空白；长度按 Unicode 码点计算，不按 UTF-16 code unit。JSON 字符串若含无法组成 Unicode 码点的未配对 UTF-16 代理项，必须在联网前拒绝。提供的文本字段去除空白后仍须满足下表的最小长度；可选字段省略时使用表中的默认值。
+
+## 完整模板字段边界
+
+根对象只允许 `schemaVersion`、`type`、`topic`、`intro`、`questions`、`allowAdditionalContext`、`expiresInSeconds`、`visual`：
+
+| 字段 | 类型与规则 |
+|---|---|
+| `schemaVersion` | 必填整数，显式选择 `1` 或 `2`；`1` 拒绝 `body`、`text` 题型和 `maxLength` |
+| `type` | 必填字符串，固定 `questionnaire` |
+| `topic` | 必填字符串，1–100 Unicode 码点 |
+| `intro` | 可选字符串，去除首尾空白后最多 1000 码点 |
+| `questions` | 必填数组，1–20 题 |
+| `allowAdditionalContext` | 可选布尔值，默认 `false`；提交补充说明最多 2000 码点 |
+| `expiresInSeconds` | 可选整数，1–604800，默认 `3600` |
+| `visual` | 必填对象，只允许 `{ "theme": "auto" }` |
+
+选择题对象只允许以下字段；v2 额外允许 `body`：
+
+| 字段 | 类型与规则 |
+|---|---|
+| `id` | 必填非空字符串；问卷内唯一、大小写敏感 |
+| `type` | 必填字符串：`single-choice` 或 `multiple-choice` |
+| `title` | 必填字符串，1–1000 码点 |
+| `shortLabel` | 必填字符串，1–20 码点 |
+| `required` | 必填布尔值 |
+| `minSelections` / `maxSelections` | 必填整数；单选固定 `1/1`；多选满足 `1 ≤ min ≤ max`，`max` 为 2–20 且不超过可选项总数；启用自定义答案时自定义项计作一项 |
+| `options` | 必填数组，每题 2–20 项 |
+| `allowCustomAnswer` | 必填布尔值，是否允许其他/自定义答案 |
+| `customAnswerMaxLength` | 可选整数；仅在允许自定义答案时提供，1–2000，默认 `2000` |
+
+每个选项对象只允许 `id`、`label`、`description`：`id` 为必填非空字符串，题内唯一、大小写敏感；`label` 为必填字符串且 1–100 码点；`description` 为可选字符串且去除首尾空白后最多 500 码点。
+
+v2 的 `body` 是可选 Markdown 字符串，原始输入最多 10000 Unicode 码点；先检查原始长度，全空白则省略，非空则保留原始内容及缩进。仅正文解释 Markdown：段落、强调、列表、引用和代码；标题、选项和答案仍为纯文本，HTML、外部图片不启用，链接显示为不可点击的文字。
+
+v2 开放题使用 `type=text`，仅允许 `id`、`type`、`title`、`shortLabel`、`required`、`body`、`maxLength`。通用字段沿用上述规则，`maxLength` 是可选整数 1–2000，默认 2000。开放题禁止选项、选择数量和自定义选项字段（包括值为 null）；选择题禁止 `maxLength`。开放题提交 `{questionId, customAnswer}`，禁止 `optionId` / `optionIds`；答案先校验原始码点长度，再去除首尾空白，提供时必须非空。未答可选题从 answers 省略，必填题必须作答。
+
+## 紧凑输入字段边界
+
+紧凑根对象只允许 `topic`、`intro`、`questions`、`allowAdditionalContext`、`expiresInSeconds`；`topic`、`intro`、题目 `title` 和选项标签遵循完整模板的文本规则。紧凑选择题只允许 `title`、`type`、`body`、`options`、`minSelections`、`maxSelections`，其中 `type` 为 `single-choice` 或 `multiple-choice`，`options` 是 2–20 个非空字符串。紧凑开放题只允许 `title`、`type=text`、`body`、`maxLength`。正文和开放题长度沿用完整模板规则。任何题提供 `body`（即使全空白）或包含开放题时自动选择 schemaVersion=2，否则为 1。紧凑输入不接受 `schemaVersion`、`visual`、ID、`shortLabel`、`required`、`allowCustomAnswer` 或其他未知字段。
+
+紧凑适配器按题目顺序生成稳定的 `q1`、`q1-o1` 等 ID，设置 `required=true`，并从标题生成不超过 20 码点的 `shortLabel`。单选范围固定为 `1/1`，不得提供范围字段；多选默认 `minSelections=1`、`maxSelections=选项数`，显式范围仍须满足完整模板规则。
+
+### 最小开放题示例
+
+以下 JSON 作为 `-CompactQuestionnaireJson` 输入：
+
+```json
+{
+  "topic": "验收标准",
+  "questions": [
+    { "title": "怎样判断这次交付符合预期？", "type": "text" }
+  ]
+}
+```
+
+## 设计纪律
+
+题型选择、问题顺序和推荐条件遵循 [ask-when-needed 的问题设计规则](../../ask-when-needed/SKILL.md#设计问题)。以下只补充问卷字段与展示要求：
+
+- 多选题应明确最少与最多选择数。
+- 选择题中，若用户可能无法选中预设项，开启 `allowCustomAnswer`。多选题中自定义答案可与预设项组合，并计入选择数。
+- 仅当问卷可能遗漏跨题信息或用户需要补充对 Agent 的要求时启用 `allowAdditionalContext`。
+- 选择题有推荐项时只标记一项，置于第一项；推荐依据、适用条件和主要代价写入 `body` 或选项 `description`（完整模板）。开放题的建议写入 `body`，不伪造选项或预填用户答案；紧凑输入仍只使用其允许字段。
+- 不设置默认选择，不用视觉权重诱导，不隐藏或移动关键提交按钮。
+- `id` 使用稳定英文 kebab-case；修改文案不应改变 ID。
+- 不把秘密、个人敏感信息或生产凭证放进题目、说明或答案。
+
+## 单题模板
+
+```json
+{
+  "schemaVersion": 1,
+  "type": "questionnaire",
+  "topic": "数据库选择",
+  "intro": "请选择本轮实现采用的数据库。",
+  "questions": [
+    {
+      "id": "database",
+      "type": "single-choice",
+      "title": "本轮使用哪种数据库？",
+      "shortLabel": "数据库",
+      "required": true,
+      "minSelections": 1,
+      "maxSelections": 1,
+      "options": [
+        { "id": "sqlite", "label": "SQLite [推荐]", "description": "本地依赖更少。" },
+        { "id": "postgresql", "label": "PostgreSQL", "description": "适合后续多实例，但运维成本更高。" }
+      ],
+      "allowCustomAnswer": true,
+      "customAnswerMaxLength": 500
+    }
+  ],
+  "allowAdditionalContext": false,
+  "expiresInSeconds": 3600,
+  "visual": { "theme": "auto" }
+}
+```
+
+## 多选与补充说明模板
+
+```json
+{
+  "schemaVersion": 1,
+  "type": "questionnaire",
+  "topic": "本轮交付范围",
+  "questions": [
+    {
+      "id": "deliverables",
+      "type": "multiple-choice",
+      "title": "本轮需要包含哪些交付物？",
+      "shortLabel": "交付物",
+      "required": true,
+      "minSelections": 2,
+      "maxSelections": 3,
+      "options": [
+        { "id": "code", "label": "代码" },
+        { "id": "tests", "label": "自动化测试" },
+        { "id": "docs", "label": "使用文档" }
+      ],
+      "allowCustomAnswer": true,
+      "customAnswerMaxLength": 500
+    }
+  ],
+  "allowAdditionalContext": true,
+  "expiresInSeconds": 3600,
+  "visual": { "theme": "auto" }
+}
+```
+
+## 提交结果映射
+
+按 `questionId` 建立映射；单选预设答案读取 `optionId`，多选预设答案读取 `optionIds`，自定义答案和开放题答案读取 `customAnswer`，由对应题型区分含义。`additionalContext` 是问卷外补充，不属于任何 `questionId`。缺失的可选题标记为 `unknown`，不得套用推荐项。

package/distribution/npm/skills/answerme/scripts/answerme-api-base-url.ps1

@@ -0,0 +1,40 @@
+function Test-AnswerMeLoopbackHost {
+    param([Parameter(Mandatory = $true)][Uri]$Uri)
+
+    $hostName = $Uri.DnsSafeHost
+    return $hostName.Equals('localhost', [StringComparison]::OrdinalIgnoreCase) -or
+        $hostName.Equals('127.0.0.1', [StringComparison]::Ordinal) -or
+        $hostName.Equals('::1', [StringComparison]::Ordinal)
+}
+
+function Resolve-AnswerMeApiBaseUrl {
+    param(
+        [AllowNull()][string]$ApiBaseUrl,
+        [switch]$AllowInsecureLoopbackHttpForTest
+    )
+
+    if ([string]::IsNullOrWhiteSpace($ApiBaseUrl)) {
+        return $null
+    }
+
+    $parsedBaseUrl = $null
+    if (-not [Uri]::TryCreate($ApiBaseUrl, [UriKind]::Absolute, [ref]$parsedBaseUrl)) {
+        throw 'API base URL must be an absolute HTTPS URL.'
+    }
+    if (-not [string]::IsNullOrEmpty($parsedBaseUrl.UserInfo) -or
+        -not [string]::IsNullOrEmpty($parsedBaseUrl.Query) -or
+        -not [string]::IsNullOrEmpty($parsedBaseUrl.Fragment) -or
+        $parsedBaseUrl.AbsolutePath -notin @('', '/')) {
+        throw 'API base URL must not include credentials, a path, a query, or a fragment.'
+    }
+    if ($parsedBaseUrl.Scheme -eq 'https') {
+        return $parsedBaseUrl
+    }
+    if ($parsedBaseUrl.Scheme -eq 'http' -and
+        $AllowInsecureLoopbackHttpForTest -and
+        (Test-AnswerMeLoopbackHost -Uri $parsedBaseUrl)) {
+        return $parsedBaseUrl
+    }
+
+    throw 'API base URL must use HTTPS; HTTP is limited to an explicit loopback test override.'
+}