aicortexpy 0.1.0__py3-none-any.whl

aicortexpy/data/default_skills/agent-memory/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: agent-memory
+description: "「记住」defaults to `aicortex memory` (never graph write). Save and recall this Agent's working memory. Use when the user asks to remember something, corrects you, or you learn durable preferences. After writing, briefly tell the user what you recorded."
+inclusion: always
+---
+
+# agent-memory
+
+当前 **Agent 自己的**工作记忆。绑定本 skill 后开通。在 Agent 详情 **Memory** 页签查看。
+
+## 默认：记住 → `aicortex memory`
+
+用户说「记住」「记录一下」「以后按这个来」、纠正你、或要跨会话保留的偏好/约定/环境事实 → **立刻**用本 skill，命令是 `aicortex memory`（`--doc long` 约定与事实，`--doc user` 用户本人）。
+
+**不要**用 `aicortex graph write`，**不要**写工作区知识库，**不要**找名叫 MEMORY 的 Collection。那些是团队知识库，和本记忆不是一回事。
+
+不要写 Hermes `~/.hermes/memories/`，不要写 `aicorkit graph memory`。
+
+任务开始时 `long` 和 `user` 已在 `.agent_context/memory.md`，不必先 `show`。查项目资料用另一个 skill：`aicortex graph search`。
+
+## 何时加载并写入
+
+出现下面任一情况，**立刻** `aicortex memory`，不要等任务结束、不要默记在对话里：
+
+- 用户要求记住某件事
+- 用户纠正你的错误，或指出正确做法（漏记下次还会犯）
+- 学到应跨会话保留的偏好、约定、环境事实
+
+## 文档
+
+| `--doc` | 含义 | 写法 |
+|---|---|---|
+| `user` | 关于用户本人：偏好、习惯、身份相关事实 | 先 show 再整篇 write，建议 < 2000 字 |
+| `long` | 本 Agent 稳定工作记忆：约定、纠错、选型 | 先 show 再整篇 write，建议 < 4000 字 |
+| `daily` | 当天短记 | 只 append；稳定了再并入 `long` |
+
+纠正工作方式 / 约定 → `long`。关于用户本人 → `user`。
+
+## 命令
+
+```
+aicortex memory show
+aicortex memory show --doc user
+aicortex memory append --doc user --content "User prefers concise replies" --heading "communication"
+aicortex memory append --doc long --content "Company git host is https://git.eniot.io/" --heading "git"
+aicortex memory write --doc long --body-file ./long.md
+aicortex memory append --doc daily --content "Decision: persist this in long after it stabilizes"
+```
+
+Windows 长文本用 `--body-file` / `--content-file`。
+
+## 写完必须反馈
+
+命令成功后，在回复里用一两句说明（不要贴全文）：
+
+- 记到哪个文档：`user` / `long` / `daily`
+- 大概记了什么
+
+例：已记到 Memory（long）：公司 Git 为 https://git.eniot.io/。
+
+## 其它
+
+任务结束有可复用结论 → `daily`；稳定事实再并入 `long`。
+
+用户**没有**明确要求保存到知识库时，一律走本 skill，不要 `aicortex graph write`。
+
+**不要存**：常识、大段日志/代码、临时路径、当前 issue 已有内容、密钥/token。

aicortexpy/data/default_skills/aicorkit-atlassian/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: aicorkit-atlassian
+description: "Jira and Confluence REST CLI. Use when the user wants to search/read/update Jira issues, agile boards/sprints, or Confluence wiki pages. Requires ~/.aicorkit config + secrets.env credentials."
+inclusion: always
+---
+
+# aicorkit-atlassian
+
+Jira issue tracking + Confluence wiki via REST API (Server & Cloud).
+
+## Platform
+
+Invoke `aicorkit` via Bash/PowerShell in the agent shell. On Windows prefer `python -m aicorkit ...`.
+
+## Requirements
+
+- `pip install aicorkit`
+- Credentials in `~/.aicorkit/secrets.env`:
+  - `ATLASSIAN_USERNAME`
+  - `ATLASSIAN_PASSWORD`
+- URLs in `~/.aicorkit/config.yaml`:
+```yaml
+atlassian:
+  jira_url: https://jira.example.com
+  confluence_url: https://wiki.example.com
+```
+- Test: `aicorkit atlassian test`
+- Windows / Linux / macOS (HTTP REST, no COM)
+
+## Usage
+
+Invoke via Bash/PowerShell. On Windows prefer `python -m aicorkit ...`.
+
+### Connection
+
+| Command | Description |
+|---------|-------------|
+| `aicorkit atlassian test` | Test Jira + Confluence connectivity and auth |
+
+### Jira — Read (no confirmation)
+
+| Command | Description |
+|---------|-------------|
+| `aicorkit jira search` | Search by JQL |
+| `aicorkit jira list-issues` | Filter by project/status/assignee (JQL sugar) |
+| `aicorkit jira get-issue` | Issue details by key |
+| `aicorkit jira list-comments` | Issue comments |
+| `aicorkit jira list-projects` | Accessible projects |
+| `aicorkit jira list-boards` | Agile boards |
+| `aicorkit jira list-sprints` | Sprints on a board |
+| `aicorkit jira list-board-issues` | Issues on board/sprint |
+
+**search**
+```
+aicorkit jira search --jql "assignee = currentUser() AND status != Done ORDER BY updated DESC" -c 20
+```
+
+**list-issues**
+```
+aicorkit jira list-issues --project CMS --status Open --assignee me -c 10
+aicorkit jira list-issues --jql "project = CMS AND updated >= -7d"
+```
+
+**get-issue / list-comments**
+```
+aicorkit jira get-issue CMS-123
+aicorkit jira list-comments CMS-123
+```
+
+**boards / sprints**
+```
+aicorkit jira list-boards --project CMS
+aicorkit jira list-sprints --board-id 945 --state active
+aicorkit jira list-board-issues --board-id 945 --sprint-id active -c 50
+```
+
+`--sprint-id` accepts numeric id or `active` / `future` / `closed`.
+
+### Jira — Write (confirm user; require `--yes`)
+
+| Command | Description |
+|---------|-------------|
+| `aicorkit jira create-issue` | Create issue |
+| `aicorkit jira add-comment` | Add comment |
+| `aicorkit jira transition` | Change status |
+| `aicorkit jira update-issue` | Update summary/description/assignee/labels |
+
+```
+aicorkit jira create-issue --project CMS --type Story --summary "标题" --description "..." --yes
+aicorkit jira add-comment CMS-123 --body "评论内容" --yes
+aicorkit jira transition CMS-123 --to "In Progress" --yes
+aicorkit jira update-issue CMS-123 --description "新描述" --assignee zheng.zhang5 --yes
+aicorkit jira update-issue CMS-123 --assignee none --yes
+```
+
+### Confluence — Read (no confirmation)
+
+| Command | Description |
+|---------|-------------|
+| `aicorkit confluence search` | Search pages (CQL or keyword) |
+| `aicorkit confluence list-spaces` | List spaces |
+| `aicorkit confluence list-pages` | Page tree in space or under parent |
+| `aicorkit confluence get-page` | Page body by id or space+title |
+
+**search**
+```
+aicorkit confluence search --space AESCESS -q "API" -c 10
+aicorkit confluence search --cql "space = AESCESS AND type = page AND lastModified >= now('-7d')"
+```
+
+**list-pages (tree)**
+```
+aicorkit confluence list-pages --space AESCESS
+aicorkit confluence list-pages --space AESCESS --parent-id 12753746
+```
+
+**get-page**
+```
+aicorkit confluence get-page --id 13069892
+aicorkit confluence get-page --space AESCESS --title "Edge需求"
+```
+
+### Confluence — Write (confirm user; require `--yes`)
+
+| Command | Description |
+|---------|-------------|
+| `aicorkit confluence update-page` | Update page (needs current `--version`) |
+| `aicorkit confluence add-comment` | Add page comment |
+
+```
+aicorkit confluence update-page --id 13069892 --version 7 --body "更新内容" --yes
+aicorkit confluence add-comment --id 13069892 --body "评论" --yes
+```
+
+Read `--version` from `get-page` output before update.
+
+## Rules
+
+1. **Read-only** (no confirmation): all `jira search/get/list-*`, all `confluence search/get/list-*`, `atlassian test`.
+2. **Mutating** (confirm user first; pass `--yes`): `jira create/add-comment/transition/update-issue`, `confluence update-page/add-comment`.
+3. Prefer `jira search` or `list-issues` then `get-issue`; for wiki use `confluence search` then `get-page`.
+4. Confluence is **not** synced to Graph — query live via CLI only.
+5. Jira Server 7.x uses REST API v2; issue keys like `PROJ-123`.
+6. WeCom group notify: use **aicorkit-wxmsg** skill.

aicortexpy/data/default_skills/aicorkit-graph/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: aicorkit-graph
+description: "Local knowledge base CLI (Memory Tree + Obsidian vault). Use when the user wants to ingest/search documents, sync email or folders into memory, query summaries, walk retrieval, or manage MEMORY.md. Run 'aicorkit graph --help' for commands."
+inclusion: always
+---
+
+# aicorkit-graph
+
+Local-first knowledge base: SQLite + Obsidian-compatible `wiki/` vault. Reference OpenHuman Memory Tree pattern.
+
+## Platform
+
+Invoke `aicorkit` via Bash/PowerShell in the agent shell.
+
+## Requirements
+
+- `pip install aicorkit[graph]` for vector search
+- Windows recommended (Outlook email ingest)
+- Optional: `DASHSCOPE_API_KEY` for dashscope embeddings / meeting archive
+
+## Storage
+
+| Scope | Default path |
+|-------|--------------|
+| Global | `~/.aicorkit/memory/` (`chunks.db` + `wiki/`) |
+| Project | `<project>/.aicorkit/memory/` via `.aicorkit/config.yaml` |
+
+Check active config: `aicorkit config paths` / `aicorkit config show`
+
+Project override example (`.aicorkit/config.yaml`):
+```yaml
+graph:
+  workspace: .aicorkit/memory
+graph_sources:
+  - id: repo-docs
+    kind: folder
+    label: 项目文档
+    path: ./docs
+    glob: "**/*.md"
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `aicorkit graph init` | Initialize chunks.db and wiki/ |
+| `aicorkit graph status` | Counts and storage size |
+| `aicorkit graph ingest document\|file\|chat\|meeting\|email` | Ingest content |
+| `aicorkit graph source *` | Configure and sync sources |
+| `aicorkit graph search` | Keyword / vector / hybrid search |
+| `aicorkit graph fetch` | Full chunk bodies by id |
+| `aicorkit graph walk` | Multi-step agentic retrieval |
+| `aicorkit graph query *` | Summary tree: source / global / topic |
+| `aicorkit graph worker *` | Async extract / seal / digest jobs |
+| `aicorkit graph vault *` | Obsidian vault path / INDEX |
+| `aicorkit graph memory *` | MEMORY.md bridge |
+| `aicorkit graph archivist` | Archive conversation JSON |
+| `aicorkit graph daemon` | Scheduled sync + worker |
+
+**init / setup**
+```
+aicorkit graph setup --yes
+aicorkit graph setup --yes --project --docs ./docs --outlook --sync --skill-platform cursor
+aicorkit graph init
+```
+
+**ingest** (requires `--yes`)
+```
+aicorkit graph ingest document --source-id "proj:v1" --title "设计" --body-file ./d.md --yes
+aicorkit graph ingest file --path ./note.md --source-id "notes:manual" --yes
+aicorkit graph ingest chat --source-id "chat:s1" --file turns.json --yes
+cat turns.json | aicorkit graph ingest chat --source-id "chat:s1" --stdin --yes
+aicorkit graph ingest meeting --file meeting.json --yes
+aicorkit graph ingest email --from outlook --folder Inbox -c 20 --yes
+```
+
+**sources & sync** (requires `--yes`)
+```
+aicorkit graph source add --kind folder --label "文档" --path D:/docs --yes
+aicorkit graph source add --kind outlook --label "收件箱" --folder Inbox --yes
+aicorkit graph source sync --all --yes
+```
+
+Kinds: `folder` | `outlook` | `web` | `notes`
+
+**search** (read-only)
+```
+aicorkit graph search "季度复盘"
+aicorkit graph search --entity "知识库"
+aicorkit graph search "API" --mode hybrid -n 10
+aicorkit graph fetch --chunk-ids "id1,id2"
+aicorkit graph walk "上周结论" -n 5
+```
+
+Team workspace knowledge in an **AICortex task**: bind collections on the Agent detail **Knowledge** tab, then `aicortex graph search`. Write with `aicortex graph write` **only** when the user explicitly asks to save to 知识库. 「记住」goes to Agent Memory (`aicortex memory`), never graph write. Do not use `aicorkit graph remote login/use` at runtime.
+
+`aicorkit graph remote login` is only for a **local laptop vault** (browse cloud collections from your machine). After login, `graph search` / `walk` / `fetch` default to local + cloud (`--scope all`). `--bind all` searches every collection in the workspace; `--bind <slug>` pins one library. Prefer editing documents in the web UI.
+
+```
+# In an Agent task (preferred)
+aicortex graph search "架构方案"
+
+# Local laptop vault only
+aicorkit graph remote login --base-url https://app-portal-pdc1.envisioniot.com/aicortex-api --token mul_... --workspace <slug>
+aicorkit graph remote use --workspace <slug>
+aicorkit graph remote collections
+```
+
+Flags: `--entity TEXT`  `--source-id TEXT`  `-n INT`  `--mode [auto|keyword|vector|hybrid]`
+
+Embed: `aicorkit config set graph.embed.provider dashscope|ollama|openai|none`
+
+**query / tree / worker**
+```
+aicorkit graph query source --id docs:design -d 7
+aicorkit graph query global -d 1
+aicorkit graph query topic --entity "知识库"
+aicorkit graph drill --node-id <node_id> --depth 1
+aicorkit graph worker run-once
+aicorkit graph worker start
+aicorkit graph tree digest --yes
+aicorkit graph entity list --hot
+aicorkit graph export -o graph.json
+```
+
+**vault / memory / ops** (mutating need `--yes`)
+```
+aicorkit graph vault open
+aicorkit graph vault index --yes
+aicorkit graph memory show
+aicorkit graph memory append --section "决策" --content "..." --yes
+aicorkit graph archivist file ./session.json --yes
+aicorkit graph dashboard --yes
+aicorkit graph daemon start --once
+```
+
+Obsidian: open vault from `aicorkit graph vault path` — browse `wiki/INDEX.md`, `sources/`, `entities/`.
+
+## Rules
+
+1. **Read-only** (no confirmation): `search`, `fetch`, `walk`, `query`, `drill`, `status`, `vault open/path`, `entity list`, `worker status`, `tree list`, `memory show/path`, `config show/paths`.
+2. **Mutating** (confirm user; use `--yes`): `ingest`, `source add/sync`, `init --force`, `tree digest`, `worker flush-stale`, `vault index`, `memory append`, `archivist`, `dashboard`, `daemon`.
+3. Prefer `walk` or `search --mode hybrid` for agent retrieval; use `fetch` to cite full chunk text.
+4. Project config overrides global — run commands from project root when using per-repo workspace.
+5. WeCom group notify: use **aicorkit-wxmsg** skill.

aicortexpy/data/default_skills/aicorkit-outlook/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: aicorkit-outlook
+description: "CLI for Outlook email/calendar via COM or HTTP bridge. Use when the user wants to read/send email, manage calendar, or run meeting audio pipeline. For local knowledge base use the separate aicorkit-graph skill."
+inclusion: always
+---
+
+# aicorkit-outlook
+
+Outlook automation via **aicorkit** (`pip install aicorkit`). Windows host may also run **aicortex-bridge** (`pip install aicortex-bridge`, same repo) for Pod deployments.
+
+## Platform
+
+| Mode | Where | How |
+|------|-------|-----|
+| **COM (local)** | Windows + Outlook desktop | `aicorkit outlook ...` |
+| **Bridge (pod)** | Linux pod + Windows host | Host: `aicortex-bridge serve`; pod: `AICORTEX_BRIDGE_URL=http://host.docker.internal:8766` |
+
+When `AICORTEX_BRIDGE_URL` is set, **aicorkit** routes `outlook *` and `graph ingest email --from outlook` over HTTP automatically. Legacy: `AICORKIT_OUTLOOK_BRIDGE_URL` / `AICORTEX_OUTLOOK_BRIDGE_URL`.
+
+Install (Windows host):
+
+```powershell
+pip install aicorkit aicortex-bridge
+aicortex-bridge serve
+```
+
+## Requirements
+
+- **Local COM:** Windows + Outlook desktop signed in
+- **Bridge:** Windows host with Outlook + `aicortex-bridge`; pod with `extra_hosts` / `host.docker.internal`
+- Linux without bridge: Outlook unavailable
+
+## Outlook — Email (CLI)
+
+| Command | Description |
+|---------|-------------|
+| `aicorkit outlook list-emails` | List recent emails (Inbox / Sent) |
+| `aicorkit outlook read-email` | Search by subject keyword, return body |
+| `aicorkit outlook send-email` | Send email |
+
+```
+aicorkit outlook list-emails -f Inbox -c 20
+aicorkit outlook read-email -q "quarterly report"
+aicorkit outlook send-email --to "a@b.com" --subject "Hello" --body "World"
+```
+
+**send-email policy** (`email.whitelist` in `~/.aicorkit/config.yaml`): only whitelisted To/CC are sent; others return `blocked: ...`.
+
+## Outlook — Calendar (CLI)
+
+| Command | Description |
+|---------|-------------|
+| `aicorkit outlook list-calendar` | Upcoming events |
+| `aicorkit outlook create-meeting` | Create meeting invitation |
+| `aicorkit outlook free-busy` | Free/busy for an email (`-e`) |
+| `aicorkit outlook list-rooms` | Frequent meeting rooms (recent calendar) |
+
+```
+aicorkit outlook list-calendar -d 14
+aicorkit outlook create-meeting --subject "Review" --start "2026-06-08 14:00" --duration 60 --attendees "team@co.com"
+aicorkit outlook free-busy -e "a@b.com" -d 7
+```
+
+## Graph + Outlook
+
+```bash
+aicorkit graph ingest email --from outlook --folder Inbox -c 20 --yes
+aicorkit graph source add --kind outlook --label "收件箱" --folder Inbox --yes
+```
+
+Uses `list_emails_full` — works via bridge when env URL is set.
+
+## Meeting (optional, COM-only)
+
+Requires `pip install aicorkit[meeting]`. Not available via bridge.
+
+```
+aicorkit meeting listen
+```
+
+## Rules
+
+1. Read-only commands — no confirmation needed.
+2. Mutating (`send-email`, `create-meeting`, `meeting listen/start`) — confirm with user first.
+3. Email addresses: semicolon-separated for multiple recipients.
+
+Knowledge base: **aicorkit-graph**. Jira/Confluence: **aicorkit-atlassian**. WeCom: **aicorkit-wxmsg**.

aicortexpy/data/default_skills/aicorkit-wxmsg/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: aicorkit-wxmsg
+description: "企业微信群机器人 Webhook 消息推送。Use when the user wants to notify a WeCom group: text, markdown, news card, image, or file. Configure wxmsg.webhook_url in ~/.aicorkit/config.yaml."
+inclusion: always
+---
+
+# aicorkit-wxmsg
+
+企业微信群机器人消息推送（Webhook REST，无额外依赖）。
+
+## Platform
+
+Invoke `aicorkit` via Bash/PowerShell in the agent shell. On Windows prefer `python -m aicorkit ...`.
+
+## Requirements
+
+- `pip install aicorkit`
+- Webhook 写入 `~/.aicorkit/config.yaml`（勿提交 git）：
+```yaml
+wxmsg:
+  webhook_url: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY
+  timeout: 30
+```
+  或命令：`aicorkit config set wxmsg.webhook_url "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=..."`
+- 也可在 `~/.aicorkit/secrets.env` 设 `WECHAT_WEBHOOK_URL`，config 里用环境变量引用
+- 测试: `aicorkit wxmsg test`
+- Windows / Linux / macOS
+
+## Usage
+
+Invoke via Bash/PowerShell. On Windows prefer `python -m aicorkit ...`.
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `aicorkit wxmsg send` | 文本 / Markdown |
+| `aicorkit wxmsg send-card` | 图文卡片（标题 + 跳转 URL + 可选封面） |
+| `aicorkit wxmsg send-image` | 本地图片（JPG/PNG ≤2M） |
+| `aicorkit wxmsg send-file` | 本地文件（≤20M，先上传再发送） |
+| `aicorkit wxmsg test` | 连通性测试 |
+
+**send** — 纯文本或 Markdown
+```
+aicorkit wxmsg send "构建完成"
+aicorkit wxmsg send --markdown "**告警** CI failed"
+aicorkit wxmsg send -f report.md --markdown-v2
+aicorkit wxmsg send --at "@all" "请尽快处理"
+echo "pipeline done" | aicorkit wxmsg send -
+```
+
+**send-card** — 带链接的卡片通知（推荐）
+```
+aicorkit wxmsg send-card --title "AICortex" \
+  --url "https://app.example.com/aicortex/" \
+  --desc "任务完成通知"
+aicorkit wxmsg send-card --title "构建完成" --url "https://ci.example.com/42" \
+  --desc "main 已通过" --picurl "https://example.com/cover.png"
+```
+- `--picurl` 须为企微可访问的 **公网 HTTPS** 图片；本地图请用 `send-image`
+- 不传 `--picurl` 时卡片仍可用，顶部显示默认占位图
+- 多条卡片：`-j '[{"title":"a","url":"https://..."}]'`（最多 8 条）
+
+**send-image / send-file** — 本地文件
+```
+aicorkit wxmsg send-image screenshot.png
+aicorkit wxmsg send-file build.log
+aicorkit wxmsg send-file report.pdf
+```
+
+**CLI 选项**
+- 覆盖 webhook：`--webhook-url` 或 `--key`
+- 预览不发送：`--dry-run`（`send` / `send-card`）
+
+## Message type guide
+
+| 场景 | 命令 |
+|------|------|
+| 简短通知 | `send` |
+| 带跳转链接 | `send-card` |
+| 发截图 | `send-image` |
+| 发日志/附件 | `send-file` |
+| 代码块/表格 | `send --markdown-v2` |
+
+## Rules
+
+1. 发送前确认 webhook 已配置（`aicorkit wxmsg test`）；配置好后无需每次加 `--webhook-url`。
+2. 结构化、可点击的通知优先 `send-card`；纯文本用 `send`。
+3. 卡片封面用 `--picurl`（远程 URL）；本地图片用 `send-image`，二者不要混用。
+4. 勿在消息或 git 中泄露 webhook key；`config.yaml` 含 key 时不要提交仓库。
+5. 单机器人 **20 条/分钟**；高频场景合并消息。
+6. 发送类命令建议先与用户确认标题、链接和正文内容。
+
+Outlook / meeting: **aicorkit-outlook** skill.
+Knowledge base: **aicorkit-graph** skill.
+Jira / Confluence: **aicorkit-atlassian** skill.

aicortexpy/data/default_skills/aicortex-basics/SKILL.md

@@ -0,0 +1,10 @@
+# AICortex basics
+
+You are running inside an AICortex workspace via the local daemon.
+
+## Rules
+
+- Prefer `aicortex` CLI with `--output json` for structured reads.
+- Final issue results go through `aicortex issue comment add`.
+- Do not @mention agents as a polite sign-off (that re-triggers runs).
+- On Windows use `--content-file` for multi-line / non-ASCII comment bodies.

aicortexpy/data/default_skills/aicortex-bridge-cdp/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: aicortex-bridge-cdp
+description: >-
+  在 aicortexpod 用本机 Chrome CDP（9222）或宿主机 aicortex-bridge（8766）打开页面、截图、UI 验收。
+  Use when the user mentions 浏览器、Chrome、CDP、DevTools、Playwright、页面测试、
+  UI 验收、打开网页、截图、中文乱码、或在 aicortexpod 里测前端。
+inclusion: always
+---
+
+# aicortex-bridge-cdp
+
+在 **aicortexpod** 里没有 Cursor IDE Browser。
+
+- **页面测试 / 截图 / 中文渲染（优先）**：容器内 **aicortex-cdp**（本机 Chrome，端口 `9222`）。镜像已装 Noto CJK / 文泉驿，避免中文方框乱码。
+- **Outlook / 宿主机已登录桌面 Chrome**：仍走 Windows **aicortex-bridge**（`AICORTEX_BRIDGE_URL`，端口 `8766`）。
+
+## 本机 CDP（截图 / 中文页，优先）
+
+```bash
+aicortex-cdp status || aicortex-cdp start
+curl -fsS http://127.0.0.1:9222/json/version
+```
+
+Playwright：
+
+```javascript
+const browser = await chromium.connectOverCDP("http://127.0.0.1:9222");
+```
+
+中文回退：镜像已装 `fonts-noto-cjk`、`fonts-wqy-microhei`、`fonts-wqy-zenhei`，Chrome 以 `--lang=zh-CN` 启动。`aicortex-cdp start` 失败时再查 `/var/log/aicortex-cdp.log`。
+
+`AICORTEX_POD_CDP=0` 可关闭入口自动拉起。
+
+## 前置（宿主机 bridge，Outlook / 桌面 Chrome）
+
+1. 宿主机已安装并启动（默认后台）：
+
+```powershell
+pip install -U aicortex-bridge
+aicortex-bridge serve
+aicortex-bridge status
+```
+
+需要 **aicortex-bridge >= 0.1.2**（含 CDP）。`0.1.1` 只有 Outlook。
+
+2. Pod 能访问 `host.docker.internal`（`docker run` 已加 `--add-host=host.docker.internal:host-gateway`）。
+3. Pod 已设置 `AICORTEX_BRIDGE_URL=http://host.docker.internal:8766`（Outlook 与 CDP 共用）。
+
+## 连接地址（宿主机 Chrome：只走 bridge，不要直连 9333）
+
+优先用环境变量：
+
+```bash
+echo "${AICORTEX_BRIDGE_URL:-未设置}"
+```
+
+默认：
+
+```text
+http://host.docker.internal:8766
+```
+
+Playwright：
+
+```javascript
+const browser = await chromium.connectOverCDP("http://host.docker.internal:8766");
+const context = browser.contexts()[0] || await browser.newContext();
+const page = context.pages()[0] || await context.newPage();
+await page.goto("https://example.com");
+```
+
+先探测再测页面：
+
+```bash
+curl -4 -s http://host.docker.internal:8766/health
+curl -4 -s http://host.docker.internal:8766/json/version
+```
+
+`/json/version` 应返回 JSON，含 `webSocketDebuggerUrl`（主机名应是 `host.docker.internal` 或 IP，**不要**再用 `ws://127.0.0.1/...`）。
+
+`host.docker.internal` 解析到 IPv6 失败时，改用：
+
+```bash
+getent ahostsv4 host.docker.internal
+# 例如 192.168.65.254
+curl -s http://192.168.65.254:8766/json/version
+```
+
+Playwright 也改成 `http://<该IPv4>:8766`。
+
+## 禁止
+
+- 不要用 Cursor IDE 的 `browser_cdp` / `cursor-ide-browser`（pod 里没有该 MCP）。
+- 截图、中文页优先连本机 `http://127.0.0.1:9222`（`aicortex-cdp`），不要为截图再起第二套 Chrome。
+- 不要从 pod 直连宿主机 `127.0.0.1:9333` 或裸访问 `http://host.docker.internal:9333`（Chrome 会拒 Host 头）。
+- 需要宿主机桌面会话时才连 `AICORTEX_BRIDGE_URL`（8766）。
+
+## 控制接口（可选）
+
+Bridge 与 Outlook 共用 `8766`：
+
+| 用途 | 请求 |
+|------|------|
+| 健康 | `GET /health`（`cdp` 应为 `up`） |
+| 状态 | `GET /v1/cdp/status` |
+| 启动 Chrome | `POST /v1/cdp/start` |
+| 停止（仅 bridge 拉起的进程） | `POST /v1/cdp/stop` |
+
+设了 `AICORTEX_BRIDGE_TOKEN` 时，`/v1/cdp/*` 需要 `Authorization: Bearer ...`。`/json` 与 `/devtools` 不需要 token。
+
+## 操作约定
+
+1. 先 `/health` + `/json/version`，不通就让用户在宿主机执行 `aicortex-bridge serve`，不要假装已经测过页面。
+2. 用已有浏览器 context/page，避免反复 newContext 把用户桌面 Chrome 搞乱。
+3. 改数据、提交表单、删除前先确认。
+4. 只读打开/检查页面无需确认。
+
+Outlook 仍用 **aicorkit-outlook**（同一 bridge 的 `/v1/outlook/*`）。