chore: add CLAUDE.md, API plan doc, and local settings

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.claude/settings.local.json

@@ -11,7 +11,8 @@
       "Bash(python scripts/search.py \"workflow flowchart status pipeline\" --domain chart)",
       "Bash(python scripts/search.py \"sidebar navigation dashboard admin\" --domain ux)",
       "Bash(npm install:*)",
-      "Bash(npx tsc:*)"
+      "Bash(npx tsc:*)",
+      "*"
     ]
   }
 }

CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

docs/agent-platform-application-api-plan.md

@@ -0,0 +1,463 @@
+# 智能体中台应用开放能力设计规划
+
+## 1. 目标定位
+
+本项目要建设一个智能体中台，用于配置、开发、发布智能体能力，并将能力以应用形式开放给外部系统调用。
+
+第一阶段的目标不是重新搭建一套运行时，而是在当前 `auto-platform` 已有多服务架构上补齐应用开放闭环：
+
+- 在平台内配置 Agent、Team、工具、技能、模型和知识能力。
+- 将一个可运行能力发布成应用。
+- 为应用生成 API Key。
+- 外部系统通过统一 API 调用应用。
+- 同步和流式调用都必须支持，其中流式调用是 V0.1 核心能力。
+- 平台记录调用审计、运行结果、错误和基础用量信息。
+
+当前仓库已有 `api-gateway`、`agent-service`、`session-service`、`auth-service`、`model-gateway-service`、`tool-service`、`skill-service`、`team-service` 等服务。本设计优先复用这些服务边界，不另起一套重复平台。
+
+## 2. 核心概念
+
+### 2.1 应用
+
+应用是对外发布单元。外部调用方不需要理解内部 Agent、Session、Run、Tool 的细节，只需要知道应用编码、调用地址和 API Key。
+
+一个应用至少包含：
+
+- 应用名称、编码、描述。
+- 应用状态：`draft`、`published`、`disabled`。
+- 运行目标类型：`agent`、`team`，后续扩展 `workflow`。
+- 运行目标 ID：绑定已发布 Agent 或 Team。
+- 默认调用配置：模型参数、输入变量、是否支持流式、超时策略。
+- API Key 列表。
+- 调用审计和运行记录。
+
+### 2.2 API Key
+
+API Key 用于外部系统调用应用接口。
+
+设计原则：
+
+- Key 明文只在创建时返回一次。
+- 数据库存储 key hash 和 key prefix，不存明文。
+- Key 必须绑定应用。
+- Key 可配置状态、过期时间和 scope。
+- Key 可被禁用或轮换。
+- 每次调用更新最后使用时间，并写入审计。
+
+当前 `api-gateway` 已有 API Key 生成、hash、prefix、状态、过期时间等基础字段，可在此基础上扩展应用绑定关系。
+
+### 2.3 外部调用
+
+外部调用分为两类：
+
+- 同步调用：请求结束后一次性返回完整回答。
+- 流式调用：使用 SSE 返回增量事件，适合聊天、长文本生成和工具执行进度展示。
+
+V0.1 必须支持 Agent 流式调用。Team 流式能力如果当前链路不足，先在 V0.2 补齐；V0.1 的 Team 调用可先走同步路径。
+
+## 3. 总体架构
+
+推荐调用路径：
+
+```text
+External Client
+  -> api-gateway
+  -> API Key validation
+  -> Application resolution
+  -> session-service
+  -> agent-service / team-service
+  -> model-gateway-service / tool-service / skill-service / memory-service
+  -> api-gateway
+  -> External Client
+```
+
+服务职责：
+
+- `api-gateway`：统一开放入口、API Key 校验、应用解析、限流、审计、SSE 代理。
+- `auth-service`：用户、角色和后台管理权限；后续可承接更完整的凭证治理。
+- `session-service`：会话、消息、run request 的持久化和状态管理。
+- `agent-service`：Agent 定义、配置、运行和 Agent 流式执行。
+- `team-service`：多 Agent 团队定义和运行。
+- `model-gateway-service`：统一模型供应商和模型调用。
+- `tool-service`、`skill-service`：工具、技能和 MCP 能力绑定。
+
+当前代码中 `agent-service` 已存在 `POST /runs/{agent_run_id}/execute-stream`，可返回 `text/event-stream`。`api-gateway` 的通用代理也已有 SSE 转发能力，但 `/gateway/sessions/execute` 在 `stream=true` 时仍返回未实现。因此应用级流式接口需要作为 V0.1 补齐重点。
+
+## 4. 应用模块设计
+
+### 4.1 应用数据模型
+
+建议新增应用实体：
+
+```text
+app_definition
+- id
+- code
+- name
+- description
+- status
+- target_type
+- target_id
+- owner_user_id
+- settings_json
+- created_time
+- updated_time
+```
+
+`target_type` 首版支持：
+
+- `agent`
+- `team`
+
+后续支持：
+
+- `workflow`
+
+`settings_json` 可保存：
+
+- `stream_enabled`
+- `default_inputs`
+- `timeout_seconds`
+- `rate_limit`
+- `metadata`
+
+### 4.2 应用 API Key 绑定
+
+建议扩展或新增应用 Key 关系：
+
+```text
+app_api_key
+- id
+- app_id
+- name
+- key_prefix
+- key_hash
+- status
+- scopes
+- expires_time
+- last_used_time
+- created_time
+- updated_time
+```
+
+scope 首版可以保持简单：
+
+- `app:invoke`
+- `app:stream`
+- `app:admin`
+
+V0.1 只需要 `app:invoke` 和 `app:stream`。
+
+### 4.3 应用调用审计
+
+建议新增调用审计：
+
+```text
+app_invocation_audit
+- id
+- app_id
+- api_key_prefix
+- request_id
+- session_id
+- run_request_id
+- target_type
+- target_id
+- invoke_type
+- status
+- duration_ms
+- error_code
+- error_message
+- client_metadata_json
+- created_time
+```
+
+`invoke_type`：
+
+- `sync`
+- `stream`
+
+## 5. 管理端接口设计
+
+管理端接口通过后台登录态访问，不直接使用外部 API Key。
+
+### 5.1 应用管理
+
+```http
+POST /gateway/apps
+POST /gateway/apps/list
+POST /gateway/apps/detail
+POST /gateway/apps/update
+POST /gateway/apps/status
+```
+
+创建应用请求示例：
+
+```json
+{
+  "code": "customer_support",
+  "name": "Customer Support",
+  "description": "External customer support assistant.",
+  "target_type": "agent",
+  "target_id": "agent_support",
+  "settings_json": {
+    "stream_enabled": true,
+    "timeout_seconds": 120
+  }
+}
+```
+
+### 5.2 应用 API Key
+
+```http
+POST /gateway/apps/{app_id}/api-keys
+POST /gateway/apps/{app_id}/api-keys/list
+POST /gateway/apps/{app_id}/api-keys/status
+```
+
+创建 Key 请求示例：
+
+```json
+{
+  "name": "production integration",
+  "scopes": "app:invoke app:stream",
+  "expires_time": null
+}
+```
+
+创建 Key 响应示例：
+
+```json
+{
+  "id": "key_001",
+  "name": "production integration",
+  "key_prefix": "agp_xxxxxxxx",
+  "api_key": "agp_full_plaintext_key_returned_once",
+  "status": "active",
+  "scopes": "app:invoke app:stream",
+  "expires_time": null,
+  "created_time": "2026-05-14T10:00:00Z"
+}
+```
+
+## 6. 外部调用接口设计
+
+外部调用统一走 `api-gateway`，请求头支持两种形式：
+
+```http
+Authorization: Bearer agp_xxx
+```
+
+或：
+
+```http
+X-API-Key: agp_xxx
+```
+
+### 6.1 同步调用
+
+```http
+POST /gateway/openapi/apps/{app_code}/chat
+Content-Type: application/json
+Authorization: Bearer agp_xxx
+```
+
+请求体：
+
+```json
+{
+  "user_id": "external-user-001",
+  "session_id": "optional-session-id",
+  "message": "帮我查询订单状态",
+  "inputs": {
+    "order_no": "SO123456"
+  },
+  "metadata": {
+    "source": "crm",
+    "trace_id": "external-trace-001"
+  }
+}
+```
+
+响应体：
+
+```json
+{
+  "request_id": "req_001",
+  "app_code": "customer_support",
+  "session_id": "ses_001",
+  "run_request_id": "run_req_001",
+  "target_type": "agent",
+  "target_id": "agent_support",
+  "status": "completed",
+  "output_text": "订单 SO123456 当前正在运输中。",
+  "output_json": null,
+  "error": null
+}
+```
+
+### 6.2 流式调用
+
+```http
+POST /gateway/openapi/apps/{app_code}/chat/stream
+Content-Type: application/json
+Accept: text/event-stream
+Authorization: Bearer agp_xxx
+```
+
+请求体与同步调用保持一致。
+
+响应类型：
+
+```http
+Content-Type: text/event-stream
+Cache-Control: no-cache
+X-Accel-Buffering: no
+```
+
+事件示例：
+
+```text
+event: started
+data: {"request_id":"req_001","session_id":"ses_001","run_request_id":"run_req_001"}
+
+event: delta
+data: {"text":"订单 "}
+
+event: delta
+data: {"text":"SO123456 当前正在运输中。"}
+
+event: completed
+data: {"status":"completed","output_text":"订单 SO123456 当前正在运输中。"}
+```
+
+失败事件示例：
+
+```text
+event: failed
+data: {"status":"failed","error_code":"model_error","error_message":"model request failed"}
+```
+
+### 6.3 流式实现要求
+
+V0.1 的流式调用必须满足：
+
+- API Key 和应用状态在开始流式响应前完成校验。
+- 响应必须使用标准 SSE 格式。
+- 每个事件必须是完整 JSON，不能输出半截 JSON。
+- 网关要透传下游 Agent stream 的 delta/completed/failed 事件。
+- 客户端断开连接时，网关必须关闭上游连接。
+- 调用审计至少记录最终状态、耗时和错误。
+- 如果目标类型暂不支持流式，返回明确 422，而不是静默降级。
+
+## 7. 后台管理 UI 设计
+
+新增“应用”模块，建议放在主导航中，与 Agents、Teams、Skills、Tools、Models 同级。
+
+### 7.1 应用列表
+
+列表展示：
+
+- 应用名称和 code。
+- 状态。
+- 绑定目标类型和目标名称。
+- 是否支持流式。
+- API Key 数量。
+- 最近调用时间。
+
+主要操作：
+
+- 新建应用。
+- 发布 / 停用应用。
+- 进入详情。
+
+### 7.2 应用详情
+
+详情页包含四个区域：
+
+- 基础配置：名称、code、描述、状态、目标类型、目标 ID。
+- 调用方式：同步接口、流式接口、请求示例、响应示例。
+- API Key：创建、禁用、查看 prefix、复制创建时返回的明文 Key。
+- 调用日志：请求时间、状态、耗时、Key prefix、错误信息。
+
+### 7.3 创建应用流程
+
+推荐表单步骤：
+
+1. 填写应用名称、code、描述。
+2. 选择运行目标：Agent 或 Team。
+3. 配置是否支持流式。
+4. 创建应用。
+5. 生成 API Key。
+6. 复制同步和流式调用示例。
+
+首版不做复杂向导，保持一个表单和一个详情页即可。
+
+## 8. V0.1 实施范围
+
+V0.1 必须完成：
+
+- 应用 CRUD。
+- 应用绑定 Agent。
+- 应用发布和停用。
+- 应用 API Key 创建、列表、禁用。
+- 外部同步调用接口。
+- 外部 Agent 流式调用接口。
+- 调用审计。
+- 管理端应用列表和详情页。
+- 同步和流式调用示例。
+
+V0.1 暂不做：
+
+- 多租户 workspace partition。
+- 复杂计费。
+- 应用 marketplace。
+- Workflow 可视化发布。
+- Team 完整流式编排。
+- 多版本灰度发布。
+
+## 9. 后续阶段
+
+### V0.2
+
+- Team 流式调用。
+- 应用调用限流。
+- API Key scope 更细粒度控制。
+- Key 轮换。
+- 调用统计和错误分析。
+
+### V0.3
+
+- Workflow 作为应用目标。
+- 应用版本发布。
+- Webhook 回调。
+- SDK 示例。
+- 前端流式调试控制台。
+
+### V0.4
+
+- 灰度发布。
+- 配额和用量报表。
+- 企业权限治理。
+- 审计导出。
+- 应用级 SLA 和告警。
+
+## 10. 验收标准
+
+文档交付验收：
+
+- 文件存在：`docs/agent-platform-application-api-plan.md`。
+- 内容包含应用模块、API Key、同步调用、流式调用、后台 UI、实施阶段和验收标准。
+- Markdown 中文可读，无乱码。
+- 不修改任何后端或前端代码。
+
+后续实现验收：
+
+- 可以创建应用并绑定已发布 Agent。
+- 可以生成应用 API Key，且明文只返回一次。
+- 使用 API Key 可以调用同步接口并得到完整回答。
+- 使用 API Key 可以调用流式接口并收到 SSE delta 事件。
+- 停用应用后，同步和流式接口都拒绝调用。
+- 停用 API Key 后，同步和流式接口都拒绝调用。
+- 流式连接断开后，上游连接被释放。
+- 调用审计能记录 app、key prefix、request id、session id、run id、状态、耗时和错误。
+