Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions docs/.agents/issue.md

Large diffs are not rendered by default.

5 changes: 2 additions & 3 deletions docs/.agents/knowledge-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,7 @@

## 协同协议与规范

- [Agent 协作协议(CLAUDE.md / AGENTS.md)](../../AGENTS.md) — 项目根工程行为准则
- [浏览器验证协议](./browser-validation.md) — 浏览器实机验证规范(A 类 claude-in-chrome 交互 / B 类系统默认 Playwright MCP 自治)
- [引用规范 (IEEE)](./reference-specifications.md) — 决策引用与文献格式
- Agent 协作协议(AGENTS.md)、浏览器验证协议、引用规范 (IEEE) — 已上移至用户级全局配置(`~/.claude/CLAUDE.md` 与 `~/.agents/docs/`),仓库不再承载 Agent 指令源
- [Wiki 文档排序元数据规范](./wiki-docs-ordering.md) — `sidebar_position`(文件 frontmatter)+ `_category_.json`(目录)驱动 docs/ → wiki 导航排序

## 工程经验沉淀
Expand Down Expand Up @@ -63,6 +61,7 @@
## 研究文献 / Research

- [Research(研究文献索引)](../research/) — 认知增强、上下文工程、Agent runtime、向量检索、知识图谱、Agent Sandbox 等领域基线调研
- [凯利公式与股市投资的数学基石](../research/quant-finance/150-kelly-criterion-and-investment-math.md) — 七块严格成立的投资数学定理(凯利仓位/统计功效/破产风险/波动拖累/复利年金/Markowitz 分散化/Sharpe 主动管理算术)+ 经多智能体交叉核验的实证数据(SPIVA/巴菲特赌局/Barber & Odean/上交所全账户研究)+ 中国市场 2026 时点可执行操作路径(个人养老金/宽基 ETF 费率/QDII 溢价/A-C 份额临界公式)与避坑清单;全文严格区分 A 类恒等式与 B 类实证统计
- [Snowflake 数据云平台深度调研](../research/retrieval-storage/034-snowflake-data-cloud.md) — 基于 Snowflake 官方文档的 10 正交维度(架构/存储/计算/数据工程/开发/AI/安全治理/数据共享/业务连续性/成本)全景调研 + 主流方案(BigQuery/Redshift/Databricks/OceanBase)横向对比与选型建议
- [ADK 2.0 升级调研](../research/agent-runtime/020b-adk-2.0-upgrade.md) — Google ADK 2.0 核心新特性、Breaking Changes、本项目影响评估与渐进式升级路径
- [Routine Agent 迭代模式调研](../research/self-evolution/110-routine-agent-iteration.md) — ReAct/Reflexion/Self-Refine/LATS/Voyager + LLM-as-Judge + Claude Code/Codex/Gemini/OpenHands 工程实践与停止护栏(长周期自主任务理论基础)
Expand Down
10 changes: 5 additions & 5 deletions docs/concepts/design/browser-automation-mcp-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ title: "浏览器操作 MCP 集成方案:Playwright MCP 全系统默认配备"
---
# 浏览器操作 MCP 集成方案:Playwright MCP 全系统默认配备

> 本文遵循 [AGENTS.md](../../../AGENTS.md) 的协作协议与循证要求。设计核心锚定:
> 本文遵循用户级全局配置 `~/.claude/CLAUDE.md` 的协作协议与循证要求。设计核心锚定:
> - 选型论证与横向盘点:[浏览器操作 MCP 调研](../../research/self-evolution/120-browser-automation-mcp.md)
> - 浏览器实机验证协议(A 类交互 / B 类自治):[browser-validation.md](../../.agents/browser-validation.md)
> - 浏览器实机验证协议(A 类交互 / B 类自治):`~/.agents/docs/browser-validation.md`
> - 全系统 MCP 注入的单一事实源:`builtin_tools(claude_code).config.mcp_config`(参见 [claude_code handler](../../../apps/negentropy/src/negentropy/engine/schedulers/handlers/claude_code.py))

## 1. 目标与约束
Expand Down Expand Up @@ -82,7 +82,7 @@ Claude Code 的相位权限([phase.py](../../../apps/negentropy/src/negentropy
## 4. 鉴权:净室默认 + dev-cookie 旁路(按需)

- **默认净室(`--isolated`)**:每会话全新 profile,适用于公开 URL 与无状态回归——开箱即用,无主机相关路径依赖。
- **鉴权回归(按需)**:回归 negentropy-ui 等需登录页面时,复用本仓既有的 **dev-cookie storageState** 旁路([playwright.config.ts](../../../apps/negentropy-ui/playwright.config.ts) + [sign-dev-cookie.mjs](../../../apps/negentropy-ui/scripts/sign-dev-cookie.mjs)):经 `--storage-state=<path>` 注入自签 `ne_sso` 登录态,**严禁**在自治环境跳转真实 OAuth/SSO 同意屏(详见 [browser-validation.md](../../.agents/browser-validation.md) 的安全红线)。配置方式见 §6。
- **鉴权回归(按需)**:回归 negentropy-ui 等需登录页面时,复用本仓既有的 **dev-cookie storageState** 旁路([playwright.config.ts](../../../apps/negentropy-ui/playwright.config.ts) + [sign-dev-cookie.mjs](../../../apps/negentropy-ui/scripts/sign-dev-cookie.mjs)):经 `--storage-state=<path>` 注入自签 `ne_sso` 登录态,**严禁**在自治环境跳转真实 OAuth/SSO 同意屏(详见 `~/.agents/docs/browser-validation.md` 的安全红线)。配置方式见 §6。

## 5. 工具面(Playwright MCP 核心工具)

Expand All @@ -108,7 +108,7 @@ Claude Code 的相位权限([phase.py](../../../apps/negentropy/src/negentropy
| `npx @latest` 不确定性 | 版本钉死;预热缓存 |
| `--no-sandbox` 降低隔离 | 限受控内部 URL;不在自治环境处理不可信外链 |
| 运行时缺浏览器/Node | 部署预装;连接失败仅告警,不阻断 |
| 真实 OAuth 被自治流程触发 | 默认净室;鉴权一律走 dev-cookie storageState([browser-validation.md](../../.agents/browser-validation.md) 红线) |
| 真实 OAuth 被自治流程触发 | 默认净室;鉴权一律走 dev-cookie storageState(`~/.agents/docs/browser-validation.md` 红线) |

## 8. Routine 浏览器实机回归验证 · 配方

Expand All @@ -129,7 +129,7 @@ acceptance_criteria:
## 9. 相关文档

- [浏览器操作 MCP 调研(选型论证)](../../research/self-evolution/120-browser-automation-mcp.md)
- [浏览器实机验证协议](../../.agents/browser-validation.md)
- 浏览器实机验证协议 — `~/.agents/docs/browser-validation.md`
- [Claude Code 集成(BuiltinTool)](../subsystems/038-claude-code-integration.md)
- [Routine 长周期自主任务系统](../subsystems/039-the-routine-system.md)
- [Interface 用户指南 §6.3 MCP Server 管理](../user-guide/interface.md)
2 changes: 1 addition & 1 deletion docs/concepts/design/context-layer.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: "Context Layer · 上下文治理层技术方案"
---
# Context Layer · 上下文治理层技术方案

> 本文遵循 [AGENTS.md](../../../AGENTS.md) 的协作协议与循证要求。
> 本文遵循用户级全局配置 `~/.claude/CLAUDE.md` 的协作协议与循证要求。
>
> 设计核心锚定:
> - **行业对标**:[Snowflake Horizon Context](https://www.snowflake.com/en/product/features/horizon-context/) · [Snowflake 数据云调研 §D7 Horizon Catalog](../../research/retrieval-storage/034-snowflake-data-cloud.md)
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/design/self-evolving-agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: "自进化 Agents Team 系统技术方案"
---
# 自进化 Agents Team 系统技术方案

> 本文遵循 [AGENTS.md](../../../AGENTS.md) 的协作协议与循证要求。
> 本文遵循用户级全局配置 `~/.claude/CLAUDE.md` 的协作协议与循证要求。
>
> 设计核心锚定:
> - 调研基础:[自进化 Agents Team 调研](../../research/self-evolution/130-self-evolving-agents-team.md)
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/design/sso.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: "单点登录(SSO)方案:Google OAuth + 用户权限管理"
---
# 单点登录 (SSO) 方案:Google OAuth + 用户权限管理

> 本文遵循 [AGENTS.md](../../../AGENTS.md) 的协作协议与循证要求。设计核心锚定:
> 本文遵循用户级全局配置 `~/.claude/CLAUDE.md` 的协作协议与循证要求。设计核心锚定:
> - 用户状态与权限的权威数据源:`user_states`(参见 [pulse.py](../../../apps/negentropy/src/negentropy/models/pulse.py))
> - 会话生命周期与用户 ID 的持久化一致性:`PostgresSessionService`(参见 [session_service.py](../../../apps/negentropy/src/negentropy/engine/adapters/postgres/session_service.py))

Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/framework.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ title: "架构设计方案 · 一核五翼总览"

### 1.2 架构哲学

系统遵循 [AGENTS.md](../../AGENTS.md) 定义的工程行为准则,核心原则包括:
系统遵循用户级全局配置 `~/.claude/CLAUDE.md` 定义的工程行为准则,核心原则包括:

- **正交分解 (Orthogonal Decomposition)**:独立变化的维度解耦,确保单一概念主体的变更具备局部性
- **复用驱动 (Composition over Construction)**:优先通过组合与集成构建系统
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/subsystems/025-the-memory-system.md
Original file line number Diff line number Diff line change
Expand Up @@ -1623,7 +1623,7 @@ timeline

### 11.1 设计哲学

遵循 [AGENTS.md](../../../../AGENTS.md) 的**反馈闭环 (Feedback Loops)** 原则:每一项工程行动都应产生可观测的反馈信号。Memory 价值量化体系的目标是:证明 Memory 子系统对 Agent 智能水平的**可测量贡献**。
遵循 `~/.claude/CLAUDE.md` 的**反馈闭环 (Feedback Loops)** 原则:每一项工程行动都应产生可观测的反馈信号。Memory 价值量化体系的目标是:证明 Memory 子系统对 Agent 智能水平的**可测量贡献**。

### 11.2 核心指标四层模型

Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/subsystems/035-the-knowledge-base.md
Original file line number Diff line number Diff line change
Expand Up @@ -829,7 +829,7 @@ flowchart LR
2. **Virtual Root 注入**:为每个被合并 Catalog 在 survivor 顶层创建一个 `node_type='CATEGORY'` 的虚拟节点,slug 加 `legacy-<short_hash>` 后缀避免冲突。
3. **子树嫁接**:将被合并 Catalog 的所有顶层 entry 的 `parent_entry_id` 重指向 virtual root,整树 `catalog_id` 一次性 UPDATE 到 survivor。
4. **WikiPublication 重指向**:`catalog_id` 改写到 survivor,状态为 `LIVE` 的降级为 `ARCHIVED`(保留多版本回退),`navigation_config` JSONB 内的 catalog_id 引用同步 rewrite。
5. **Tombstone**:源 Catalog 设 `is_archived=true, merged_into_id=survivor.id`,**严禁物理删除**(与 [AGENTS.md 数据库管理规范](../../../../AGENTS.md) 一致)。
5. **Tombstone**:源 Catalog 设 `is_archived=true, merged_into_id=survivor.id`,**严禁物理删除**(与 `~/.claude/CLAUDE.md` 的 Database Management 规范一致)。
6. **守恒断言**:迁移末尾 SELECT 校验 `count(doc_catalog_entries)` 与 `count(DISTINCT document_id)` 守恒。

**回退性**:Phase A(仅加索引/列)的 downgrade 完全可逆;**Phase B(合并)声明 `DESTRUCTIVE_DOWNGRADE = true`,downgrade 不会反向拆分子树**——回退依赖 Phase B 执行前的强制 `pg_dump` 快照。
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/subsystems/036-the-knowledge-graph.md
Original file line number Diff line number Diff line change
Expand Up @@ -1440,4 +1440,4 @@ timeline

---

> **文档维护**:本文档与代码同步演进。架构变更时需同步更新对应章节,保持代码事实与文档描述的一致性。变更遵循 [AGENTS.md](../../../../AGENTS.md) 中的 Verification Before Done 定式。
> **文档维护**:本文档与代码同步演进。架构变更时需同步更新对应章节,保持代码事实与文档描述的一致性。变更遵循 `~/.claude/CLAUDE.md` 中的 Verification Before Done 定式。
2 changes: 1 addition & 1 deletion docs/concepts/subsystems/037-federated-kg.md
Original file line number Diff line number Diff line change
Expand Up @@ -237,7 +237,7 @@ Feature flag:`NE_KNOWLEDGE_FEATURE_FLAGS__ENABLE_CROSS_CORPUS_KG`

## 11. 浏览器实机验证清单(P0 必跑)

按 [浏览器验证协议](../../../agents/browser-validation.md) 用 `mcp__chrome_devtools` 复用用户已登录 Chrome:
按浏览器验证协议(`~/.agents/docs/browser-validation.md`)用 `mcp__chrome_devtools` 复用用户已登录 Chrome:

- [ ] 单 @Corpus → Planner 启用但无 bridges
- [ ] 多 @Corpus + intent=fact → Planner 启用,bridges 可能为空
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/user-guide/chat-essentials.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ title: "Home 对话 · 主模块特性手册"
## 0. 入口

- 浏览器打开 `https://<your-domain>/`(首页即 Home 对话)。
- 自签 dev cookie 注入流程参见 [agents/browser-validation.md](../agents/browser-validation.md)
- 自签 dev cookie 注入流程参见 `~/.agents/docs/browser-validation.md`

## 1. 发起对话与模型选择

Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/user-guide/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,7 @@ Wiki 使用 ISR 机制,最长 5 分钟自动更新。如需立即更新,可
| [QA 流水线](../design/qa-delivery-pipeline.md) | `docs/concepts/design/qa-delivery-pipeline.md` | 质量门禁与发布流程 |
| [Wiki 运维](../../reference/wiki/ops.md) | `docs/reference/wiki/ops.md` | Wiki 站点的部署与运维 |
| [工程变更日志](../operations/engineering-changelog.md) | `docs/concepts/engineering-changelog.md` | 里程碑与基线变更记录 |
| [AI 协作协议](../../../AGENTS.md) | `AGENTS.md` | Agent 协作准则与工程规范 |
| AI 协作协议 | `~/.claude/CLAUDE.md` | Agent 协作准则与工程规范 |

---

Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/user-guide/memory-automation.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,4 +128,4 @@ pg_dump -h localhost -U postgres negentropy_db \
-t negentropy.memory_core_blocks --data-only > core_blocks_$(date +%Y%m%d).sql
```

> 数据迁移操作严禁直接删除现有数据,参考 [`AGENTS.md`](../../../AGENTS.md) "Database Management" 章节。
> 数据迁移操作严禁直接删除现有数据,参考 `~/.claude/CLAUDE.md` 的 "Database Management" 章节。
2 changes: 1 addition & 1 deletion docs/concepts/user-guide/skills-troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,5 +106,5 @@ skills_injector_unresolved_refs owner_id=... missing=[...]
- 上手 → [`skills-basics.md`](./skills-basics.md)
- 进阶 → [`skills-advanced.md`](./skills-advanced.md)
- 原理与架构 → [`../design/skills.md`](../design/skills.md)
- 浏览器验证协议 → [`../agents/browser-validation.md`](../agents/browser-validation.md)
- 浏览器验证协议 → `~/.agents/docs/browser-validation.md`
- Issue 追踪 → [`../issue.md`](../agents/issue.md)(搜索 Skills / ISSUE-045)
2 changes: 1 addition & 1 deletion docs/i18n/zh-CN/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -227,7 +227,7 @@ graph TB
| [QA 流水线](../../concepts/design/qa-delivery-pipeline.md) | 质量门禁与发布流程 |
| [SSO 集成](../../concepts/design/sso.md) | Google OAuth 认证配置 |
| [工程变更日志](../../concepts/operations/engineering-changelog.md) | 里程碑与基线变更记录 |
| [AI 协作协议](../../../AGENTS.md) | Agent 协作行为准则与工程规范 |
| AI 协作协议(`~/.claude/CLAUDE.md`) | Agent 协作行为准则与工程规范 |

</center>

Expand Down
6 changes: 3 additions & 3 deletions docs/reference/perceives/agents/knowledge-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@ title: "Knowledge Map · 知识索引"

## 协作约定

- [AGENTS.md](../../AGENTS.md) — 工程行为准则、命令规范、Pre-commit 流程。
- [browser-validation.md](./browser-validation.md) — 浏览器自动化与登录态约束。
- [reference-specifications.md](./reference-specifications.md) — IEEE 引用规范。
- `AGENTS.md` — 工程行为准则、命令规范、Pre-commit 流程。
- `browser-validation.md` — 浏览器自动化与登录态约束。
- `reference-specifications.md` — IEEE 引用规范。

## PDF Pipeline

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/perceives/issue.md
Original file line number Diff line number Diff line change
Expand Up @@ -198,7 +198,7 @@ Internal error: directory mismatch for directory ".../anthropics/claude-code-act

### 根因

1. 仓库根目录的 [CLAUDE.md](../CLAUDE.md) 是指向 [AGENTS.md](../AGENTS.md) 的 symlink,用于避免双份 Agent 指令造成 SSoT 分裂。
1. 仓库根目录的 `CLAUDE.md` 是指向 `AGENTS.md` 的 symlink,用于避免双份 Agent 指令造成 SSoT 分裂。
2. `anthropics/claude-code-action@v1` 在 `pull_request` 场景会先快照 PR 侧的敏感启动配置,再删除并从 base 分支恢复可信版本,以防 PR 修改 `.mcp.json` / `.claude/` / `CLAUDE.md` 注入启动行为。
3. 该 action 当前对 PR 侧 `CLAUDE.md` symlink 的快照路径存在兼容性问题,导致审查 step 提前失败;workflow 用 `continue-on-error: true` 包住该 step,因此 overall check 仍为 success,但 sticky comment 会污染 PR 讨论。
4. workflow 过去只检查 `ANTHROPIC_API_KEY` 是否非空,无法识别 secret 已过期、被撤销或填错;action 直到调用 SDK 才报 `Invalid API key` 并发布错误评论。
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/wiki/design/knowledge-graph.md
Original file line number Diff line number Diff line change
Expand Up @@ -214,7 +214,7 @@ Wiki 场景定位于"**只读浏览 + 点击跳转**"。我们**精简重做**

### 浏览器实机回归

按 [浏览器验证协议](../../../agents/browser-validation.md) 接入用户常用 Chrome 主 profile:
按浏览器验证协议(`~/.agents/docs/browser-validation.md`)接入用户常用 Chrome 主 profile:

1. 现有 `/`、`/[pubSlug]`、`/[pubSlug]/[...entrySlug]` 不受影响
2. `/[pubSlug]/graph` SSG 首屏可见节点、无客户端等待
Expand Down
Loading