agentquad 0.4.1 → 0.4.3

package/src/codex-agent-installer.js

@@ -0,0 +1,165 @@
+/**
+ * Codex agent installer：
+ *   - 写 ~/.codex/config.toml 的 [mcp_servers.agentquad] 表（marker 注释包起来）
+ *   - 装 ~/.codex/skills/agentquad-child/SKILL.md
+ *
+ * marker 实现：TOML 文件支持注释，用 `# <<< agentquad managed start ... # >>> end` 注释行
+ * 包裹一段以 newline 分隔的 toml block；卸载时按注释边界精确删。
+ */
+import { existsSync, mkdirSync, readFileSync, copyFileSync, rmSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { writeFileAtomic } from './agent-installer-shared.js'
+
+const SKILL_NAME = 'agentquad-child'
+const MARKER_START = '# <<< agentquad managed start — do not edit by hand >>>'
+const MARKER_END = '# <<< agentquad managed end >>>'
+
+function defaultConfigTomlPath() {
+  return join(homedir(), '.codex', 'config.toml')
+}
+
+function defaultSkillsDir() {
+  return join(homedir(), '.codex', 'skills')
+}
+
+function defaultSkillTemplatePath() {
+  return fileURLToPath(new URL('./templates/agent-skills/agentquad-child.skill.md', import.meta.url))
+}
+
+function buildBlock({ port, version }) {
+  return [
+    MARKER_START,
+    `# agentquad-version: ${version}`,
+    `# agentquad-port: ${port}`,
+    `# agentquad-generated-at: ${new Date().toISOString()}`,
+    '[mcp_servers.agentquad]',
+    `url = "http://127.0.0.1:${port}/mcp"`,
+    'transport = "http"',
+    MARKER_END,
+    '',
+  ].join('\n')
+}
+
+function stripExistingBlock(raw) {
+  const startIdx = raw.indexOf(MARKER_START)
+  if (startIdx === -1) return { raw, found: false }
+  const endIdx = raw.indexOf(MARKER_END, startIdx)
+  if (endIdx === -1) return { raw, found: false }
+  const afterEnd = raw.indexOf('\n', endIdx)
+  const head = startIdx === 0
+    ? ''
+    : raw.slice(0, startIdx).replace(/\n+$/, '\n')
+  const tail = afterEnd === -1 ? '' : raw.slice(afterEnd + 1)
+  return { raw: head + tail, found: true }
+}
+
+function parseExistingBlock(raw) {
+  const startIdx = raw.indexOf(MARKER_START)
+  if (startIdx === -1) return null
+  const endIdx = raw.indexOf(MARKER_END, startIdx)
+  if (endIdx === -1) return null
+  const block = raw.slice(startIdx, endIdx + MARKER_END.length)
+  const versionM = block.match(/# agentquad-version:\s*(\S+)/)
+  const portM = block.match(/# agentquad-port:\s*(\d+)/)
+  return {
+    version: versionM ? versionM[1] : null,
+    port: portM ? Number(portM[1]) : null,
+  }
+}
+
+export function installAgent({
+  configTomlPath = defaultConfigTomlPath(),
+  skillsDir = defaultSkillsDir(),
+  skillTemplatePath = defaultSkillTemplatePath(),
+  port,
+  version,
+} = {}) {
+  if (!port) throw new Error('port_required')
+  if (!version) throw new Error('version_required')
+
+  const changes = []
+  const cur = existsSync(configTomlPath) ? readFileSync(configTomlPath, 'utf8') : ''
+  const existing = parseExistingBlock(cur)
+  const sameAll = existing && existing.version === version && existing.port === port
+
+  let next
+  if (sameAll) {
+    // idempotent — 不动文件，保留原 generatedAt
+    next = cur
+  } else {
+    const { raw: stripped } = stripExistingBlock(cur)
+    const block = buildBlock({ port, version })
+    const sep = stripped && !stripped.endsWith('\n') ? '\n' : ''
+    next = stripped + sep + block
+    changes.push('mcp_registered')
+  }
+
+  if (next !== cur) {
+    writeFileAtomic(configTomlPath, next)
+  }
+
+  // skill
+  const skillDir = join(skillsDir, SKILL_NAME)
+  const skillFile = join(skillDir, 'SKILL.md')
+  if (!existsSync(skillFile) || readFileSync(skillFile, 'utf8') !== readFileSync(skillTemplatePath, 'utf8')) {
+    mkdirSync(skillDir, { recursive: true })
+    copyFileSync(skillTemplatePath, skillFile)
+    changes.push('skill_installed')
+  }
+
+  return { ok: true, changes, configPath: configTomlPath, skillPath: skillFile }
+}
+
+export function uninstallAgent({
+  configTomlPath = defaultConfigTomlPath(),
+  skillsDir = defaultSkillsDir(),
+} = {}) {
+  const removed = []
+  if (existsSync(configTomlPath)) {
+    const cur = readFileSync(configTomlPath, 'utf8')
+    const { raw, found } = stripExistingBlock(cur)
+    if (found) {
+      writeFileAtomic(configTomlPath, raw)
+      removed.push('mcp_block')
+    }
+  }
+  const skillDir = join(skillsDir, SKILL_NAME)
+  if (existsSync(skillDir)) {
+    rmSync(skillDir, { recursive: true, force: true })
+    removed.push('skill')
+  }
+  return { ok: true, removed }
+}
+
+export function inspectAgent({
+  configTomlPath = defaultConfigTomlPath(),
+  skillsDir = defaultSkillsDir(),
+  expectedPort = null,
+} = {}) {
+  const out = {
+    target: 'codex',
+    mcpRegistered: false,
+    skillPresent: false,
+    drift: false,
+    configPath: configTomlPath,
+    expectedPort,
+    actualPort: null,
+    version: null,
+  }
+  if (existsSync(configTomlPath)) {
+    try {
+      const cur = readFileSync(configTomlPath, 'utf8')
+      const parsed = parseExistingBlock(cur)
+      if (parsed) {
+        out.mcpRegistered = true
+        out.actualPort = parsed.port
+        out.version = parsed.version
+      }
+    } catch { /* malformed/unreadable, treat as not registered */ }
+  }
+  if (existsSync(join(skillsDir, SKILL_NAME, 'SKILL.md'))) out.skillPresent = true
+  if (out.mcpRegistered && expectedPort && out.actualPort !== expectedPort) out.drift = true
+  return out
+}

package/src/config.js

@@ -336,6 +336,12 @@ function defaultConfig() {
 			timeoutMs: 600_000,
 			redact: true,
 		},
+		agents: {
+			autoBootstrap: 'prompt',         // 'prompt' | 'never' | 'silent'
+			bootstrapDismissed: false,        // CLI 弹问时用户回 N 后置 true
+			enabled: { claude: true, codex: true, cursor: true },
+			warnPtyCount: 8,                  // doctor 软 warning 阈值
+		},
 };
 }
 

package/src/cursor-agent-installer.js

@@ -0,0 +1,128 @@
+/**
+ * Cursor agent installer：
+ *   - 写 ~/.cursor/mcp.json 的 mcpServers.agentquad（带 _agentquadManaged 旁路 marker）
+ *   - 装 ~/.cursor/rules/agentquad.mdc
+ *
+ * Cursor 不是 AgentQuad spawn 的，没有运行时注入（C），只走 B + rule。
+ */
+import { existsSync, mkdirSync, readFileSync, copyFileSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { buildMarker, isAgentquadManaged, writeJsonAtomic } from './agent-installer-shared.js'
+
+const RULE_FILE = 'agentquad.mdc'
+
+function defaultMcpJsonPath() {
+  return join(homedir(), '.cursor', 'mcp.json')
+}
+
+function defaultRulesDir() {
+  return join(homedir(), '.cursor', 'rules')
+}
+
+function defaultMdcTemplatePath() {
+  return fileURLToPath(new URL('./templates/agent-skills/agentquad-child.cursor.mdc', import.meta.url))
+}
+
+function readMcpJson(path) {
+  if (!existsSync(path)) return {}
+  const raw = readFileSync(path, 'utf8')
+  if (!raw.trim()) return {}
+  try { return JSON.parse(raw) } catch (e) { throw new Error(`malformed_cursor_mcp_json: ${e.message}`) }
+}
+
+export function installAgent({
+  mcpJsonPath = defaultMcpJsonPath(),
+  rulesDir = defaultRulesDir(),
+  mdcTemplatePath = defaultMdcTemplatePath(),
+  port,
+  version,
+} = {}) {
+  if (!port) throw new Error('port_required')
+  if (!version) throw new Error('version_required')
+
+  const changes = []
+  const cur = readMcpJson(mcpJsonPath)
+  cur.mcpServers = cur.mcpServers || {}
+
+  const desired = { url: `http://127.0.0.1:${port}/mcp`, transport: 'http' }
+  const prev = cur.mcpServers.agentquad
+  const prevMarker = cur._agentquadManaged
+  const samePort = prev && prev.url === desired.url
+  const sameVersion = prevMarker && prevMarker.version === version
+
+  cur.mcpServers.agentquad = desired
+  if (samePort && sameVersion && isAgentquadManaged(cur)) {
+    cur._agentquadManaged = prevMarker
+  } else {
+    cur._agentquadManaged = buildMarker({ version, port })
+    changes.push('mcp_registered')
+  }
+  writeJsonAtomic(mcpJsonPath, cur)
+
+  const ruleFile = join(rulesDir, RULE_FILE)
+  if (!existsSync(ruleFile) || readFileSync(ruleFile, 'utf8') !== readFileSync(mdcTemplatePath, 'utf8')) {
+    mkdirSync(rulesDir, { recursive: true })
+    copyFileSync(mdcTemplatePath, ruleFile)
+    changes.push('rule_installed')
+  }
+
+  return { ok: true, changes, configPath: mcpJsonPath, rulePath: ruleFile }
+}
+
+export function uninstallAgent({
+  mcpJsonPath = defaultMcpJsonPath(),
+  rulesDir = defaultRulesDir(),
+} = {}) {
+  const removed = []
+  if (existsSync(mcpJsonPath)) {
+    const cur = readMcpJson(mcpJsonPath)
+    if (cur.mcpServers?.agentquad) {
+      delete cur.mcpServers.agentquad
+      removed.push('mcp_entry')
+    }
+    if (cur._agentquadManaged) {
+      delete cur._agentquadManaged
+      removed.push('marker')
+    }
+    if (removed.length > 0) writeJsonAtomic(mcpJsonPath, cur)
+  }
+  const ruleFile = join(rulesDir, RULE_FILE)
+  if (existsSync(ruleFile)) {
+    unlinkSync(ruleFile)
+    removed.push('rule')
+  }
+  return { ok: true, removed }
+}
+
+export function inspectAgent({
+  mcpJsonPath = defaultMcpJsonPath(),
+  rulesDir = defaultRulesDir(),
+  expectedPort = null,
+} = {}) {
+  const out = {
+    target: 'cursor',
+    mcpRegistered: false,
+    skillPresent: false,  // rulePresent 对外仍叫 skillPresent，便于 dispatcher 统一展示
+    drift: false,
+    configPath: mcpJsonPath,
+    expectedPort,
+    actualPort: null,
+    version: null,
+  }
+  if (existsSync(mcpJsonPath)) {
+    try {
+      const cur = readMcpJson(mcpJsonPath)
+      if (cur.mcpServers?.agentquad?.url) {
+        out.mcpRegistered = true
+        const m = cur.mcpServers.agentquad.url.match(/:(\d+)\//)
+        if (m) out.actualPort = Number(m[1])
+        out.version = cur._agentquadManaged?.version || null
+      }
+    } catch { /* malformed */ }
+  }
+  if (existsSync(join(rulesDir, RULE_FILE))) out.skillPresent = true
+  if (out.mcpRegistered && expectedPort && out.actualPort !== expectedPort) out.drift = true
+  return out
+}

package/src/lark-api-client.js

@@ -1,5 +1,25 @@
 import * as Lark from '@larksuiteoapi/node-sdk'
 import { toLarkText } from './lark-markdown.js'
+import { isMarkdownLike, toLarkPost } from './lark-post.js'
+
+/**
+ * 决定一段文本走 text 还是 post 路径。
+ *   - 'text' / 'post' 强制选定
+ *   - 'auto'（默认）：含块级 markdown 特征才升级到 post
+ * 任何非法值视为 'auto'。
+ */
+function resolveFormat(format, text) {
+  if (format === 'text' || format === 'post') return format
+  return isMarkdownLike(text) ? 'post' : 'text'
+}
+
+function buildTextContent(text) {
+  return JSON.stringify({ text: toLarkText(String(text)) })
+}
+
+function buildPostContent(text) {
+  return JSON.stringify(toLarkPost(String(text)))
+}
 
 function isBlank(value) {
   return value == null || String(value) === ''
@@ -44,17 +64,35 @@ export function createLarkApiClient({ appId, appSecret, clientFactory = defaultC
     return client
   }
 
-  async function sendMessage({ chatId, text } = {}) {
+  async function sendMessage({ chatId, text, format = 'auto' } = {}) {
     if (!hasCredentials()) return { ok: false, reason: 'lark_credentials_missing' }
     if (isBlank(chatId)) return { ok: false, reason: 'chatId_required' }
     if (isBlank(text)) return { ok: false, reason: 'text_required' }
+    const useFormat = resolveFormat(format, String(text))
+    if (useFormat === 'post') {
+      try {
+        const response = await getClient().im.message.create({
+          params: { receive_id_type: 'chat_id' },
+          data: {
+            receive_id: String(chatId),
+            msg_type: 'post',
+            content: buildPostContent(text),
+          },
+        })
+        return { ok: true, payload: normalizePayload(response) }
+      } catch (e) {
+        // post 路径被飞书拒收（字段超限 / API 异常）→ 静默降级到 text，不丢消息
+        const detail = normalizeError(e)
+        logger.warn?.(`[lark-api] send post failed, falling back to text: ${detail}`)
+      }
+    }
     try {
       const response = await getClient().im.message.create({
         params: { receive_id_type: 'chat_id' },
         data: {
           receive_id: String(chatId),
           msg_type: 'text',
-          content: JSON.stringify({ text: toLarkText(String(text)) }),
+          content: buildTextContent(text),
         },
       })
       return { ok: true, payload: normalizePayload(response) }
@@ -65,16 +103,33 @@ export function createLarkApiClient({ appId, appSecret, clientFactory = defaultC
     }
   }
 
-  async function replyInThread({ rootMessageId, text } = {}) {
+  async function replyInThread({ rootMessageId, text, format = 'auto' } = {}) {
     if (!hasCredentials()) return { ok: false, reason: 'lark_credentials_missing' }
     if (isBlank(rootMessageId)) return { ok: false, reason: 'rootMessageId_required' }
     if (isBlank(text)) return { ok: false, reason: 'text_required' }
+    const useFormat = resolveFormat(format, String(text))
+    if (useFormat === 'post') {
+      try {
+        const response = await getClient().im.message.reply({
+          path: { message_id: String(rootMessageId) },
+          data: {
+            msg_type: 'post',
+            content: buildPostContent(text),
+            reply_in_thread: true,
+          },
+        })
+        return { ok: true, payload: normalizePayload(response) }
+      } catch (e) {
+        const detail = normalizeError(e)
+        logger.warn?.(`[lark-api] reply post failed, falling back to text: ${detail}`)
+      }
+    }
     try {
       const response = await getClient().im.message.reply({
         path: { message_id: String(rootMessageId) },
         data: {
           msg_type: 'text',
-          content: JSON.stringify({ text: toLarkText(String(text)) }),
+          content: buildTextContent(text),
           reply_in_thread: true,
         },
       })

package/src/lark-bot.js

@@ -183,18 +183,18 @@ export function createLarkBot({
     return apiClient
   }
 
-  async function sendMessage({ chatId, text } = {}) {
+  async function sendMessage({ chatId, text, format } = {}) {
     if (isBlank(chatId)) return { ok: false, reason: 'chatId_required' }
     if (isBlank(text)) return { ok: false, reason: 'text_required' }
     if (!hasCredentials()) return { ok: false, reason: 'lark_credentials_missing' }
-    return getApiClient().sendMessage({ chatId, text })
+    return getApiClient().sendMessage({ chatId, text, format })
   }
 
-  async function replyInThread({ rootMessageId, text } = {}) {
+  async function replyInThread({ rootMessageId, text, format } = {}) {
     if (isBlank(rootMessageId)) return { ok: false, reason: 'rootMessageId_required' }
     if (isBlank(text)) return { ok: false, reason: 'text_required' }
     if (!hasCredentials()) return { ok: false, reason: 'lark_credentials_missing' }
-    return getApiClient().replyInThread({ rootMessageId, text })
+    return getApiClient().replyInThread({ rootMessageId, text, format })
   }
 
   async function sendCard({ chatId, card } = {}) {
@@ -219,9 +219,9 @@ export function createLarkBot({
 
   // thread root 失效时（用户撤回 / 飞书 5xx）静默 drop。"撤回 root" = 用户明示
   // "不想看这个对话了"，把消息泼到群主消息流是污染。reply 失败就让它失败。
-  async function deliverReply({ chatId, rootMessageId, text } = {}) {
-    if (!rootMessageId) return sendMessage({ chatId, text })
-    return replyInThread({ rootMessageId, text })
+  async function deliverReply({ chatId, rootMessageId, text, format } = {}) {
+    if (!rootMessageId) return sendMessage({ chatId, text, format })
+    return replyInThread({ rootMessageId, text, format })
   }
 
   function clearPendingReplyRetry(replyContext, ev) {