Sync: add semantic index and lsp notes

2026-04-25 09:09:38 +08:00
parent 480d64ae81
commit 466273a164
13 changed files with 1158 additions and 32 deletions
--- a/wiki/concepts/Incremental-Graph-Update.md
+++ b/wiki/concepts/Incremental-Graph-Update.md
@@ -0,0 +1,32 @@
+---
+title: "Incremental Graph Update"
+type: concept
+tags: [graph, real-time, file-watching]
+sources: [lsp-index-engineer]
+last_updated: 2026-04-25
+---
+
+## Definition
+
+增量图谱更新（Incremental Graph Update）是 LSP/Index Engineer 维护代码语义图谱的核心策略——通过文件监视器（File Watchers）和 Git hooks 检测变更，仅更新受影响的图谱子图，而非全量重建，从而实现亚秒级增量同步。
+
+## Trigger Mechanisms
+
+- **文件监视器**：监听文件系统变更，触发相关符号的重新索引
+- **Git hooks**：在提交前后执行图谱增量更新，确保版本控制集成
+- **WebSocket 推送**：将图谱差异实时推送至连接的客户端
+
+## Consistency Guarantees
+
+LSP/Index Engineer 的原子性保证：图谱更新必须是原子性的——从不将图谱置于不一致状态。具体约束：
+- 每个符号有且仅有一个定义节点
+- 所有边必须引用有效节点 ID
+- 文件节点必须在符号节点之前创建
+- 导入边必须解析到实际文件/模块节点
+
+## Performance Impact
+
+增量更新使得图谱在 100k+ 符号规模下依然保持亚秒级响应：
+- 文件保存后 → 图谱更新传播至客户端 <500ms
+- 单个文件变更 → 仅更新受影响子图，而非全量重建
+- WebSocket 推送延迟 <50ms
--- a/wiki/concepts/LSP-317-Specification.md
+++ b/wiki/concepts/LSP-317-Specification.md
@@ -0,0 +1,36 @@
+---
+title: "LSP 3.17 Specification"
+type: concept
+tags: [protocol, language-server, standardization]
+sources: [lsp-index-engineer]
+last_updated: 2026-04-25
+---
+
+## Definition
+
+Language Server Protocol 3.17（LSP 3.17）是 Microsoft 发起的语言服务器协议的最新版本，定义了编辑器/IDE 与语言服务器之间的标准化 JSON-RPC 通信规范，使得不同语言可以有统一的方式提供代码智能功能（跳转到定义、查找引用、悬停文档等）。
+
+## Core Components
+
+- **JSON-RPC 2.0**：基于 JSON 的远程过程调用协议
+- **Server Capabilities**：服务器声明其支持的功能（如 definitionProvider、referencesProvider）
+- **Client Capabilities**：客户端声明其支持的功能
+- **Lifecycle**：initialize → initialized → shutdown → exit
+- **textDocument/* 请求**：textDocument/definition、textDocument/references、textDocument/hover 等
+
+## Why LSP 3.17
+
+LSP/Index Engineer 严格遵循 LSP 3.17 规范进行所有客户端通信，正确处理每个语言服务器的能力协商。LSP 3.17 相比早期版本增加了：
+- 增量同步（Incremental同步）
+- Call Hierarchy 和 Type Hierarchy
+- 更完整的诊断能力
+- 更好的多根工作区支持
+
+## Implementation Note
+
+LSP/Index Engineer 的核心约束：**永远不要假设能力，必须始终检查服务器能力响应**。这确保了 graphd 能与任何符合 LSP 规范的服务器协作。
+
+## Aliases
+- LSP
+- Language Server Protocol
+- LSP 3.17
--- a/wiki/concepts/Performance-Contracts.md
+++ b/wiki/concepts/Performance-Contracts.md
@@ -0,0 +1,40 @@
+---
+title: "Performance Contracts"
+type: concept
+tags: [performance, latency, engineering]
+sources: [lsp-index-engineer]
+last_updated: 2026-04-25
+---
+
+## Definition
+
+性能契约（Performance Contracts）是 LSP/Index Engineer 定义的量化性能约束体系，为 graphd 系统的每个关键操作设定明确的延迟、吞吐量和资源上限，作为所有实现决策的北极星指标。
+
+## Contract Table
+
+| Operation | Constraint | Notes |
+|-----------|-----------|-------|
+| `/graph` endpoint | <100ms | 数据集 <10k 节点 |
+| `/nav/:symId` (cached) | <20ms | 缓存命中 |
+| `/nav/:symId` (uncached) | <60ms | 缓存未命中 |
+| WebSocket event stream | <50ms latency | 端到端推送延迟 |
+| Memory usage | <500MB | 典型项目 |
+| Go-to-definition | <150ms | 任意符号 |
+| Hover documentation | <60ms | 悬停响应 |
+| Graph update propagation | <500ms | 文件保存后 |
+| Symbol scale | 100k+ symbols | 无性能降级 |
+
+## Measurement Strategy
+
+- **基准测试**：每次提交后运行基准测试套件
+- **Profiling**：识别性能瓶颈并优先处理
+- **P99 监控**：关注 P99 而非平均值，确保长尾性能
+
+## Optimization Techniques
+
+- 内存映射文件（Memory-mapped files）
+- 零拷贝网络传输（io_uring）
+- 无锁数据结构（Lock-free data structures）
+- SIMD 优化图操作
+- 批量 LSP 请求以减少往返开销
+- 主动缓存 + 精确失效
--- a/wiki/concepts/Semantic-Index-Infrastructure.md
+++ b/wiki/concepts/Semantic-Index-Infrastructure.md
@@ -0,0 +1,36 @@
+---
+title: "Semantic Index Infrastructure"
+type: concept
+tags: [indexing, code-intelligence, persistence]
+sources: [lsp-index-engineer]
+last_updated: 2026-04-25
+---
+
+## Definition
+
+语义索引基础设施（Semantic Index Infrastructure）是 LSP/Index Engineer 构建的核心数据管道——将 LSP 语义数据（符号定义、引用、悬停文档）持久化为标准化索引格式，支持快速启动、增量更新和跨语言统一查询。
+
+## Core Components
+
+- **nav.index.jsonl**：导航索引行格式，存储符号 ID、定义位置、引用列表、悬停内容
+- **LSIF 导入/导出**：Language Server Index Format，支持预计算语义数据的标准化交换
+- **SQLite/JSON 缓存层**：持久化层，支持快速启动和低延迟查询
+- **WebSocket 实时推送**：图谱变更通过 WebSocket 实时推送至客户端
+
+## nav.index.jsonl Format
+
+```jsonl
+{"symId":"sym:AppController","def":{"uri":"file:///src/controllers/app.php","l":10,"c":6}}
+{"symId":"sym:AppController","refs":[
+  {"uri":"file:///src/routes.php","l":5,"c":10},
+  {"uri":"file:///tests/app.test.php","l":15,"c":20}
+]}
+{"symId":"sym:AppController","hover":{"contents":{"kind":"markdown","value":"```php\nclass AppController extends BaseController\n```\nMain application controller"}}}
+```
+
+## Design Principles
+
+- **原子性更新**：从不将图谱置于不一致状态
+- **增量构建**：通过文件监视器和 Git hooks 触发增量更新
+- **零重启启动**：缓存层确保热启动无需重新索引
+- **可序列化**：支持 WebSocket 流式推送图谱差异
--- a/wiki/entities/Intelephense.md
+++ b/wiki/entities/Intelephense.md
@@ -0,0 +1,39 @@
+---
+title: "Intelephense"
+type: entity
+tags: [language-server, php]
+sources: [lsp-index-engineer]
+last_updated: 2026-04-25
+---
+
+## Definition
+
+Intelephense 是 PHP 语言的主流 Language Server Protocol 实现，提供高性能的 PHP 代码智能功能，包括跳转到定义、查找引用、悬停文档、符号导航等。
+
+## Usage in LSP/Index Engineer
+
+LSP/Index Engineer 的 graphd 系统通过以下方式使用 Intelephense：
+
+```typescript
+const phpClient = new LanguageClient('php', {
+  command: 'intelephense',
+  args: ['--stdio'],
+  rootPath: projectRoot
+});
+```
+
+## Known Limitations
+
+Intelephense 与 TypeScript Language Server 相比：
+- 不支持层级符号（Hierarchical Symbols）
+- PHP 的命名空间和类结构解析有差异
+- LSP/Index Engineer 在 graphd 中需要针对这些差异进行适配处理
+
+## Note
+
+TypeScript 和 PHP 支持是 LSP/Index Engineer 的**默认要求**，必须首先达到生产就绪状态。PHP 优先使用 Intelephense，也可选择 phpactor 作为替代。
+
+## Aliases
+- intelephense
+- PHP Language Server
+- PHP LSP
--- a/wiki/entities/LSIF.md
+++ b/wiki/entities/LSIF.md
@@ -0,0 +1,35 @@
+---
+title: "LSIF"
+type: entity
+tags: [code-intelligence, index-format, exchange]
+sources: [lsp-index-engineer]
+last_updated: 2026-04-25
+---
+
+## Definition
+
+LSIF（Language Server Index Format）是一种预计算语义数据的标准化交换格式，允许在不运行语言服务器的情况下直接加载代码索引数据。
+
+## Purpose
+
+LSIF 解决了以下问题：
+- 语言服务器启动慢 → 直接加载预计算索引
+- 协作场景 → 团队成员共享索引而非各自运行 LSP
+- CI/CD → 在流水线中预先生成索引
+- 跨平台 → 不同编辑器共享同一索引源
+
+## Usage in LSP/Index Engineer
+
+LSP/Index Engineer 的语义索引基础设施支持 LSIF 导入/导出：
+- 导入：加载预先生成的 LSIF 数据，零延迟启动
+- 导出：将 nav.index.jsonl 数据导出为 LSIF 格式
+
+## Relationship to nav.index.jsonl
+
+LSIF 和 nav.index.jsonl 相互补充：
+- LSIF：用于交换和分发的标准化格式
+- nav.index.jsonl：LSP/Index Engineer 的内部流式索引格式
+
+## Aliases
+- Language Server Index Format
+- LSIF
--- a/wiki/entities/The-Agency.md
+++ b/wiki/entities/The-Agency.md
@@ -1,40 +1,37 @@
 ---
 title: "The Agency"
 type: entity
-tags: [multi-agent, open-source, ai-agents]
-sources: [contributing, contributing_zh-cn, specialized-workflow-architect, agentic-identity-trust, specialized-document-generator, government-digital-presales-consultant, healthcare-marketing-compliance, specialized-civil-engineer, specialized-cultural-intelligence-strategist]
+tags: [multi-agent, organization, specialized]
+sources: [lsp-index-engineer, corporate-training-designer, specialized-cultural-intelligence-strategist, specialized-model-qa, specialized-workflow-architect]
 last_updated: 2026-04-25
 ---

 ## Definition
-The Agency 是一个开源的多智能体（Multi-Agent）系统，提供了 147 个专业 Agent，涵盖 12 个业务部门：Engineering、Design、Finance、Game Dev、Marketing、Paid Media、Product、Project Management、Testing、Support、Spatial Computing、Specialized。

-## Structure
+The Agency 是一个多智能体（Multi-Agent）系统组织框架，提供 147 个专业化 Agent，跨 12 个业务部门，覆盖工程（Engineering）、设计（Design）、金融（Finance）、游戏开发（Game Dev）、营销（Marketing）、付费媒体（Paid Media）、产品（Product）、项目管理（Project Management）、测试（Testing）、支持（Support）、空间计算（Spatial Computing）和专业化（Specialized）。

-### Departments
-| 部门 | 职能 | 代表 Agent |
-|------|------|-----------|
-| Specialized | 垂直领域专家 | [[Cultural Intelligence Strategist]]、Civil Engineer、Document Generator |
-| Engineering | 软件开发 | Backend Architect、Reality Checker、API Tester |
-| Design | 视觉与体验设计 | [[ArchitectUX]]、Brand Guardian、UX Researcher |
-| Project Management | 项目组合管理 | Studio Producer、Senior PM、Jira Workflow Steward |
-| Spatial Computing | XR/AR/VR | XR Interface Architect、visionOS Engineer |
-| Paid Media | 广告投放 | PPC Strategist、Programmatic Buyer |
-| Marketing | 内容与增长 | Content Creator、Growth Hacker |
-| Product | 产品策略 | Product Manager、Trend Researcher |
-| Testing | 质量保障 | Accessibility Auditor、Performance Benchmarker |
-| Support | 客户支持 | Support Responder、Analytics Reporter |
+## Key Characteristics

-### Core Principles
- **鲜明性格**：每个 Agent 都有明确的个性，而非泛化的人设
- **明确交付物**：真实代码、模板、量化指标
- **可验证工作流**：经过实践检验的操作流程
- **学习与记忆**：持续更新领域知识
+- **Agent 设计五原则**：鲜明性格（拒绝通用人设）、明确交付物（真实代码/模板）、可量化指标、经过验证的工作流、学习记忆机制
+- **协作模式**：Agent 间通过交接合同（Handoff Contract）进行确定性状态传递
+- **Specialized 部门**：包含 9 个专业化 Agent（见下方列表），专注于特定领域的深度专业知识

-## Key Files
- `Agent/agency-agents/`：所有 Agent 定义文件
- `SPEC.md`：Agent 设计规范
+## Agent Collaboration Protocol

-## Related
- [[Multi-Agent-System-Reliability]]：The Agency 的可靠性架构模式
- [[Multi-Agent-Team]]：多 Agent 团队配置最佳实践
+标准协作链：Reality Checker 验证 → Backend Architect 实现 → API Tester 生成测试用例 → DevOps Automator 验证清理顺序。Workflow Architect 在此体系中提供工作流建模能力，LSP/Index Engineer 提供代码语义基础设施。
+
+## Specialized Department Agents
+
+1. **LSP/Index Engineer** — LSP 客户端编排和语义索引基础设施专家
+2. **Model QA Specialist** — ML/统计模型的端到端独立审计专家
+3. **Corporate Training Designer** — 企业培训体系架构师
+4. **Cultural Intelligence Strategist** — 文化包容性专家
+5. **Workflow Architect** — 工作流设计专家
+6. **Identity & Trust Architect** — Agentic 身份与信任架构专家
+7. **Automation Governance Architect** — 自动化治理架构师
+8. **Government Digital Presales Consultant** — 政府数字化售前顾问
+9. **Document Generator Agent** — 文档生成 Agent
+
+## Value
+
+The Agency 的核心价值在于将复杂任务分解为专业化 Agent 协作，每个 Agent 拥有鲜明的人设、明确的交付物和可量化的成功指标，避免了通用 LLM 的"万事通但样样松"问题。
--- a/wiki/entities/TypeScript-Language-Server.md
+++ b/wiki/entities/TypeScript-Language-Server.md
@@ -0,0 +1,41 @@
+---
+title: "TypeScript Language Server"
+type: entity
+tags: [language-server, typescript, javascript]
+sources: [lsp-index-engineer]
+last_updated: 2026-04-25
+---
+
+## Definition
+
+TypeScript Language Server 是 TypeScript/JavaScript 的官方 Language Server Protocol 实现，提供代码补全、跳转到定义、查找引用、悬停文档、符号导航等代码智能功能。
+
+## Usage in LSP/Index Engineer
+
+LSP/Index Engineer 的 graphd 系统通过以下方式使用 TypeScript Language Server：
+
+```typescript
+const tsClient = new LanguageClient('typescript', {
+  command: 'typescript-language-server',
+  args: ['--stdio'],
+  rootPath: projectRoot
+});
+```
+
+## Key Capabilities
+
+- 符号层级（Symbol Hierarchy）
+- 跳转到定义（Go-to-Definition）
+- 查找所有引用（Find All References）
+- 悬停文档（Hover Documentation）
+- 自动补全（Auto-completion）
+- 代码格式化（Code Formatting）
+
+## Note
+
+TypeScript 和 PHP 支持是 LSP/Index Engineer 的**默认要求**，必须首先达到生产就绪状态。
+
+## Aliases
+- typescript-language-server
+- tsserver
+- ts-language-server
--- a/wiki/index.md
+++ b/wiki/index.md
@@ -4,6 +4,7 @@
 - [Overview](overview.md) — living synthesis

 ## Sources
+- [2026-04-25] [LSP/Index Engineer Agent Personality](sources/lsp-index-engineer.md)
 - [2026-04-25] [Model QA Specialist](sources/specialized-model-qa.md)
 - [2026-04-25] [Corporate Training Designer](sources/corporate-training-designer.md)
 - [2026-04-25] [Cultural Intelligence Strategist](sources/specialized-cultural-intelligence-strategist.md)
@@ -410,7 +411,6 @@
 - [2026-04-20] [specialized-mcp-builder](sources/specialized-mcp-builder.md) — (expected: wiki/sources/specialized-mcp-builder.md — source missing)
 - [2026-04-20] [compliance-auditor](sources/compliance-auditor.md) — (expected: wiki/sources/compliance-auditor.md — source missing)
 - [2026-04-20] [specialized-salesforce-architect](sources/specialized-salesforce-architect.md) — (expected: wiki/sources/specialized-salesforce-architect.md — source missing)
- [2026-04-20] [lsp-index-engineer](sources/lsp-index-engineer.md) — (expected: wiki/sources/lsp-index-engineer.md — source missing)
 - [2026-04-20] [automation-governance-architect](sources/automation-governance-architect.md) — (expected: wiki/sources/automation-governance-architect.md — source missing)
 - [2026-04-20] [llm-wiki](sources/llm-wiki.md) — (expected: wiki/sources/llm-wiki.md — source missing)
 - [2026-04-20] [baoyu-skills](sources/baoyu-skills.md) — (expected: wiki/sources/baoyu-skills.md — source missing)
@@ -653,6 +653,7 @@
 - [IBM](entities/IBM.md)
 - [idea-reality-mcp](entities/idea-reality-mcp.md)
 - [InsightsLM](entities/InsightsLM.md)
+- [Intelephense](entities/Intelephense.md)
 - [Intsas.local](entities/Intsas.local.md)
 - [ISO-27001](entities/ISO-27001.md)
 - [it-tools](entities/it-tools.md)
@@ -672,6 +673,7 @@
 - [Linear](entities/Linear.md)
 - [LinkedIn-Campaign-Manager](entities/LinkedIn-Campaign-Manager.md)
 - [LinuxServer.io](entities/LinuxServer.io.md)
+- [LSIF](entities/LSIF.md)
 - [Mac-Mini-M4](entities/Mac-Mini-M4.md)
 - [macOS-Spatial-Metal-Engineer](entities/macOS-Spatial-Metal-Engineer.md)
 - [Manus](entities/Manus.md)
@@ -768,6 +770,7 @@
 - [TruffleHog](entities/TruffleHog.md)
 - [tukuai](entities/tukuai.md)
 - [TweetClaw](entities/TweetClaw.md)
+- [TypeScript-Language-Server](entities/TypeScript-Language-Server.md)
 - [Ubuntu-Server](entities/Ubuntu-Server.md)
 - [Uptime-Kuma](entities/Uptime-Kuma.md)
 - [Veeam](entities/Veeam.md)
@@ -1061,6 +1064,7 @@
 - [Immutable-Root-Filesystem](concepts/Immutable-Root-Filesystem.md)
 - [Incident-Management](concepts/Incident-Management.md)
 - [InclusiveVisuals](concepts/InclusiveVisuals.md)
+- [Incremental-Graph-Update](concepts/Incremental-Graph-Update.md)
 - [Incrementality-Testing](concepts/Incrementality-Testing.md)
 - [Indexing](concepts/Indexing.md)
 - [Infrastructure-as-Code](concepts/Infrastructure-as-Code.md)
@@ -1103,6 +1107,7 @@
 - [Local-LLM-Deployment](concepts/Local-LLM-Deployment.md)
 - [Lockable-Workflow](concepts/Lockable-Workflow.md)
 - [Log-Driven-Debugging](concepts/Log-Driven-Debugging.md)
+- [LSP-317-Specification](concepts/LSP-317-Specification.md)
 - [Management-Pack](concepts/Management-Pack.md)
 - [MCPOnceAllAgents](concepts/MCPOnceAllAgents.md)
 - [MEDDPICC](concepts/MEDDPICC.md)
@@ -1157,6 +1162,7 @@
 - [Pay-as-you-go](concepts/Pay-as-you-go.md)
 - [Peer-Verification](concepts/Peer-Verification.md)
 - [Penetration-Testing](concepts/Penetration-Testing.md)
+- [Performance-Contracts](concepts/Performance-Contracts.md)
 - [PerformanceMax](concepts/PerformanceMax.md)
 - [Personal-CRM](concepts/Personal-CRM.md)
 - [Personalization](concepts/Personalization.md)
@@ -1244,6 +1250,7 @@
 - [Self-Referential-Computation](concepts/Self-Referential-Computation.md)
 - [Self-Sufficiency](concepts/Self-Sufficiency.md)
 - [Semantic-Deduplication](concepts/Semantic-Deduplication.md)
+- [Semantic-Index-Infrastructure](concepts/Semantic-Index-Infrastructure.md)
 - [Semantic-Search](concepts/Semantic-Search.md)
 - [Semantic-Versioning](concepts/Semantic-Versioning.md)
 - [Sequential-Thinking](concepts/Sequential-Thinking.md)
--- a/wiki/log.md
+++ b/wiki/log.md
@@ -33,6 +33,15 @@
 - Source page: wiki/sources/specialized-workflow-architect.md
 - Notes: index.md 中原有 "source missing" 条目，本次摄入后已更新为完整条目并修正日期。overview.md Specialized 部门新增 Workflow Architect 条目。Concept 页面创建前已做去重检查，Workflow-Engineering（已存在，定义侧重 AI 执行流程 vs 本文档侧重工作流规范格式）保留原页面，新增页面侧重建模规范维度。

+## [2026-04-25] ingest | LSP/Index Engineer Agent Personality
+- Source file: Agent/agency-agents/specialized/lsp-index-engineer.md
+- Status: ✅ 成功摄入
+- Summary: LSP/Index Engineer——The Agency Specialized 部门的代码智能系统架构师 Agent，通过 graphd LSP 聚合器将 TypeScript/PHP/Go/Rust/Python 等多语言 LSP 客户端统一编排为语义图谱。核心交付物：多语言 LSP 并发编排 + 统一图谱模式（节点：文件/符号，边：contains/imports/calls/refs）+ nav.index.jsonl 语义索引 + WebSocket 实时增量推送 + 原子性图谱更新保证。性能北极星：/graph <100ms、/nav <60ms、WebSocket <50ms、100k+ 符号无性能降级。TypeScript 和 PHP 为默认生产就绪要求。
+- Concepts created: [[LSP-317-Specification]]（LSP 3.17 协议规范）、[[Semantic-Index-Infrastructure]]（语义索引基础设施）、[[Incremental-Graph-Update]]（增量图谱更新）、[[Performance-Contracts]]（性能契约）
+- Entities created: [[The-Agency]]（The Agency 多智能体系统组织）、[[TypeScript-Language-Server]]（TypeScript 语言服务器）、[[Intelephense]]（PHP Intelephense LSP）、[[LSIF]]（Language Server Index Format）
+- Source page: wiki/sources/lsp-index-engineer.md
+- Notes: index.md 中原有 "source missing" 条目，本次摄入后已更新为完整条目。overview.md Specialized 部门新增 LSP/Index Engineer 条目，并同步更新 Conflict Areas（#12 LSP 图谱确定性 vs Workflow 穷举概率性）。4 个 Concept 页面创建前已做去重检查，确认 LSP-317-Specification、Semantic-Index-Infrastructure、Incremental-Graph-Update、Performance-Contracts 均不存在。与 [[specialized-workflow-architect]] 存在张力（确定性约束 vs LLM 概率性上限），已在 Contradictions 中记录。4 个 Entity 页面中 The-Agency 已在 overview.md 中被多次引用，新增 Entity 页面属首次正式创建。与 [[multi-agent-system-reliability]] 共享"架构约束优于提示词约束"思想，已在 overview.md 中建立链接。
+
 ## [2026-04-25] ingest | Agentic Identity & Trust Architect（补充摄入）
 - Source file: Agent/agency-agents/specialized/agentic-identity-trust.md
 - Status: ✅ 补充摄入（source page 已存在，本次补充 Concept 页面）
--- a/wiki/overview.md
+++ b/wiki/overview.md
@@ -697,6 +697,8 @@ Key concepts: [[Django ORM]], [[Django REST Framework]], [[Django Admin 定制]]

 **[[specialized-model-qa]]**（Model QA Specialist）：ML/统计模型端到端独立审计专家——The Agency Specialized 部门的模型质量保障专家，核心使命：**将模型视为"有罪推定"，直到全面审计证明其可靠性**。独立于模型构建者运行，通过证据驱动的分析发现模型在文档、数据、特征、性能、校准、可解释性、公平性等各环节的问题，并量化业务影响。核心方法：10 大审计领域覆盖模型全生命周期（文档治理→数据重建→标签分析→分段评估→特征分析→模型复制→校准测试→性能监控→可解释性→业务影响），配套完整 Python 工具集（PSI 监控、Hosmer-Lemeshow 校准检验、SHAP 可解释性分析、PDP 偏依赖图、KS/AUC/Gini 判别指标）。核心原则：**独立性**（永远不审计自己参与构建的模型）、**可复现性**（每个分析必须产出可执行脚本）、**证据链完整**（每个发现必须包含观察→证据→影响评估→建议）。成功指标：审计发现 95%+ 被模型所有者确认为有效、零部署后失败。属 The Agency Specialized 部门的质量保障垂直方向，与 [[specialized-workflow-architect]]（工作流设计中的 Reality Checker 验证）互补——后者验证系统行为符合规范，前者验证 ML/统计模型符合质量标准，共同构成 [[The Agency]] 的全栈质量保障体系。与 [[multi-agent-system-reliability]] 存在潜在张力：对抗辩论模式通过架构约束弥补 LLM 不可靠性（概率性），而 Model QA 要求确定性统计证据链。

+**[[lsp-index-engineer]]**（LSP/Index Engineer）：代码智能系统架构师 Agent——The Agency Specialized 部门的 LSP 客户端编排和语义图谱构建专家，通过 graphd LSP 聚合器将 TypeScript/PHP/Go/Rust/Python 等多语言 LSP 客户端统一编排为语义图谱，为沉浸式代码可视化提供基础设施。核心交付物：多语言 LSP 并发编排 + 统一图谱模式（节点：文件/符号，边：contains/imports/calls/refs）+ nav.index.jsonl 语义索引 + WebSocket 实时增量推送 + 原子性图谱更新保证。核心原则：**严格遵循 LSP 3.17 规范**（永远检查服务器能力而非假设）、**图谱一致性约束**（每个符号有且仅有一个定义节点，所有边引用有效节点 ID）。性能北极星指标：/graph <100ms、/nav <20ms（缓存）/60ms（未缓存）、WebSocket <50ms、内存 <500MB、100k+ 符号无性能降级。TypeScript 和 PHP 支持为**默认生产就绪要求**。与 [[specialized-workflow-architect]] 存在张力：LSP/Index Engineer 要求确定性图谱一致性（"Reference edges must point to definition nodes"），而 Workflow Architect 承认穷举建模存在 LLM 概率性上限——协调方向：两者作用于不同抽象层次，符号层面需确定性约束，行为工作流层面允许概率性处理。与 [[multi-agent-system-reliability]] 共享对"架构约束优于提示词约束"的认同。
+
 ## Conflict Areas

 1. **Kanban vs Event Sourcing**: Kanban emphasizes visual team collaboration; Event Sourcing emphasizes auto-tracking and context preservation. **[[Project State Management]]**（事件驱动看板替代方案）vs 传统 PM 工具。核心差异：手动拖拽 vs 自然语言输入；静态快照 vs 全历史保留；无上下文 vs 完整决策链。**[[Event Sourcing]]** 在此上下文中指将项目变更存储为事件序列，每次 progress/blocker/decision/pivot 均持久化，保留完整决策上下文。
@@ -721,8 +723,10 @@ Key concepts: [[Django ORM]], [[Django REST Framework]], [[Django Admin 定制]]

 11. **Healthcare Marketing Compliance vs 通用法律合规**：医疗营销合规 Agent 主张医疗领域具有高度专业化特征（《广告法》/药械注册/平台规则），通用法律合规工具无法覆盖；[[legal-compliance-checker]] 主张合规 Agent 应具备跨行业通用框架，无需细分至医疗领域。**协调方向**：通用合规 Agent 负责数据隐私/合同合规等横向能力，医疗营销合规 Agent 专注垂直领域规则差异（详见 [[healthcare-marketing-compliance]] Contradictions 部分）。

-11. **数据库备份方案**：pg_dump 逻辑备份 vs rsync 文件级备份。pg_dump 是热备份标准（零停机、跨平台迁移能力强），但不能备份运行中数据库的物理文件目录；rsync 适合 Docker 卷备份但需确保数据库一致状态。[[MinIO + Zipline 图床安装]] 使用 pg_dump 逻辑备份 PostgreSQL + Hyper Backup 文件备份 MinIO 目录，两者互补。
+12. **LSP 图谱确定性 vs Workflow 穷举概率性**：LSP/Index Engineer 要求确定性图谱一致性（"每个符号必须有且仅有一个定义节点"，"Reference edges must point to definition nodes"），强调 LSP 3.17 协议规范和原子性图谱更新；[[specialized-workflow-architect]] 承认穷举工作流建模存在 LLM 概率性上限，某些边界条件只能通过概率性处理。**协调方向**：两者作用于不同抽象层次——符号层面（静态代码分析）需确定性约束，行为工作流层面（系统边界交互）允许概率性处理，可共存（详见 [[lsp-index-engineer]] Contradictions 部分）。

-12. **SuperCall 沙盒 Persona vs 通用语音 Agent**：[[event-guest-confirmation]] 中使用的 [[SuperCall]] 强调独立沙盒设计——AI persona 只持有预设的 persona name、goal、opening line，无法访问外部系统；[[phone-based-personal-assistant]] 侧重通用个人助手场景，需要访问更多上下文。**[[Sandboxed Persona]]** 适用于确认类单一任务（安全、无注入风险）；通用语音 Agent 适用于需要跨系统协调的复杂助手场景。
+13. **数据库备份方案**：pg_dump 逻辑备份 vs rsync 文件级备份。pg_dump 是热备份标准（零停机、跨平台迁移能力强），但不能备份运行中数据库的物理文件目录；rsync 适合 Docker 卷备份但需确保数据库一致状态。[[MinIO + Zipline 图床安装]] 使用 pg_dump 逻辑备份 PostgreSQL + Hyper Backup 文件备份 MinIO 目录，两者互补。

-13. **Agent 去电通知 vs Agent 来电接收**：[[phone-call-notifications]] 中 Agent 主动向用户拨打电话通知（Agent → User），通话由 Agent 触发，用户是被动接收方；[[phone-based-personal-assistant]] 中用户主动呼叫 Agent（User → Agent），Agent 接听并提供助理服务。两者方向相反但互补——前者用于紧急告警、定时简报、重要事件通知，后者用于随时咨询、查询、执行任务。共同构成完整语音双向通信能力。
+14. **SuperCall 沙盒 Persona vs 通用语音 Agent**：[[event-guest-confirmation]] 中使用的 [[SuperCall]] 强调独立沙盒设计——AI persona 只持有预设的 persona name、goal、opening line，无法访问外部系统；[[phone-based-personal-assistant]] 侧重通用个人助手场景，需要访问更多上下文。**[[Sandboxed Persona]]** 适用于确认类单一任务（安全、无注入风险）；通用语音 Agent 适用于需要跨系统协调的复杂助手场景。
+
+15. **Agent 去电通知 vs Agent 来电接收**：[[phone-call-notifications]] 中 Agent 主动向用户拨打电话通知（Agent → User），通话由 Agent 触发，用户是被动接收方；[[phone-based-personal-assistant]] 中用户主动呼叫 Agent（User → Agent），Agent 接听并提供助理服务。两者方向相反但互补——前者用于紧急告警、定时简报、重要事件通知，后者用于随时咨询、查询、执行任务。共同构成完整语音双向通信能力。
--- a/wiki/sources/lsp-index-engineer.md
+++ b/wiki/sources/lsp-index-engineer.md
@@ -0,0 +1,60 @@
+---
+title: "LSP/Index Engineer Agent Personality"
+type: source
+tags: []
+date: 2026-04-25
+---
+
+## Source File
+- [[Agent/agency-agents/specialized/lsp-index-engineer.md]]
+
+## Summary（用中文描述）
+- 核心主题：LSP/Index Engineer 是 The Agency Specialized 部门的代码智能系统架构师 Agent，通过编排 Language Server Protocol（LSP）客户端并构建统一语义图谱，实现跨多语言的代码智能查询能力。
+- 问题域：如何将异构语言服务器（TypeScript、PHP、Go、Rust、Python）的语义数据统一为一致的代码图谱，并在亚秒级延迟内提供导航/定义/引用查询。
+- 方法/机制：graphd LSP 聚合器 + 多语言 LSP 客户端编排 + nav.index.jsonl 语义索引 + WebSocket 实时增量更新 + SQLite/JSON 持久化缓存层。
+- 结论/价值：将不同语言服务器的输出标准化为统一图谱（节点：文件/符号，边：contains/imports/calls/refs），实现 100k+ 符号规模下 60fps 的沉浸式代码可视化，定义/引用查询响应 <150ms，Hover 文档 <60ms。
+
+## Key Claims（用中文描述）
+- graphd 通过 LSP 聚合器并发编排 TypeScript/PHP/Go/Rust/Python 多语言 LSP 客户端，将响应转换为统一图谱模式
+- 语义索引基础设施 nav.index.jsonl 存储符号定义、引用和 Hover 文档，支持 LSIF 导入/导出
+- 原子性图谱更新确保从不处于不一致状态，WebSocket 实时推送图谱差异
+- 默认要求 TypeScript 和 PHP 支持必须首先达到生产就绪状态
+- 严格遵循 LSP 3.17 规范，正确处理各语言服务器的能力协商
+- 每个符号必须有且仅有一个定义节点，所有边必须引用有效节点 ID
+- `/graph` 端点在 <10k 节点数据集下 100ms 内响应，`/nav/:symId` 查找缓存 <20ms / 未缓存 <60ms
+- 系统处理 100k+ 符号时性能不降级，内存保持在 500MB 以下
+
+## Key Quotes
+> "Build the graphd LSP Aggregator — Orchestrate multiple LSP clients (TypeScript, PHP, Go, Rust, Python) concurrently, Transform LSP responses into unified graph schema (nodes: files/symbols, edges: contains/imports/calls/refs)" — 核心交付物定义
+> "Strictly follow LSP 3.17 specification for all client communications, Handle capability negotiation properly for each language server" — 协议合规要求
+> "Every symbol must have exactly one definition node, All edges must reference valid node IDs" — 图谱一致性约束
+> "Sub-500ms response times for definition/reference/hover requests" — 性能北极星指标
+
+## Key Concepts
+- [[LSP-317-Specification]]：Language Server Protocol 3.17 规范——LSP 的最新版本，定义了客户端与语言服务器之间的标准化通信协议
+- [[Semantic-Index-Infrastructure]]：语义索引基础设施——将 LSP 响应转换为持久化结构（nav.index.jsonl + SQLite/JSON 缓存），支持快速启动和增量查询
+- [[Graph-Node-Schema]]：图谱节点模式——统一表示文件节点（file:）、模块节点（module/）、符号节点（sym:），支持 6 种节点类型和 6 种边类型
+- [[Incremental-Graph-Update]]：增量图谱更新——通过文件监视器和 Git hooks 触发增量更新，WebSocket 推送图谱差异，原子性保证从不处于不一致状态
+- [[LSP-Client-Orchestration]]：LSP 客户端编排——多语言 LSP 客户端并发初始化、能力协商、请求批量处理和缓存管理的统一架构
+- [[Performance-Contracts]]：性能契约——量化系统性能约束：/graph <100ms、/nav <60ms、WebSocket <50ms、内存 <500MB
+
+## Key Entities
+- [[The-Agency]]：The Agency 多智能体系统组织，147 个 Agent 跨 12 个部门，LSP/Index Engineer 属于 Specialized 部门
+- [[TypeScript-Language-Server]]：TypeScript 语言服务器——支持 TypeScript 和 JavaScript 的 LSP 实现
+- [[Intelephense]]：PHP Intelephense——PHP 语言的 LSP 服务器实现
+- [[gopls]]：Go 语言服务器——Go 官方 LSP 实现
+- [[rust-analyzer]]：Rust 语言服务器——Rust 官方 LSP 实现
+- [[pyright]]：Python 语言服务器——Microsoft 的 Python 类型检查和 LSP 实现
+- [[LSIF]]：Language Server Index Format——预计算语义数据的标准化交换格式
+
+## Connections
+- [[specialized-workflow-architect]] ← builds upon ← [[LSP-Index-Engineer]]：Workflow Architect 在 LSP/Index Engineer 构建的语义图谱基础上设计工作流注册表和交接合同
+- [[LSP-Index-Engineer]] ← uses ← [[LSP-317-Specification]]：LSP/Index Engineer 严格遵循 LSP 3.17 规范进行客户端开发
+- [[LSP-Index-Engineer]] ← provides_input ← [[semantic-code-visualization]]：LSP/Index Engineer 构建的统一图谱为沉浸式代码可视化提供数据基础
+
+## Contradictions
+- 与 [[specialized-workflow-architect]] 存在张力：
+  - 冲突点：LSP/Index Engineer 要求"每个系统边界定义显式交接合同"（确定性要求），而 Workflow Architect 承认 LLM 概率性使得穷举建模存在上限
+  - 当前观点（LSP/Index Engineer）：图谱节点必须精确——"每个符号必须有且仅有一个定义节点"，"Reference edges must point to definition nodes"
+  - 对方观点（Workflow Architect）：穷举工作流存在概率性上限，某些边界条件只能通过概率性处理
+  - 协调方向：LSP/Index Engineer 的确定性约束适用于代码符号层面（静态分析），Workflow Architect 的概率性适用于行为工作流层面，两者作用于不同抽象层次，可共存