Update nexus wiki content
This commit is contained in:
27
wiki/Charlie-Munger.md
Normal file
27
wiki/Charlie-Munger.md
Normal file
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: "Charlie Munger"
|
||||
type: entity
|
||||
tags: [investing, strategy, mental-models]
|
||||
sources: [zk-steward]
|
||||
last_updated: 2026-05-30
|
||||
---
|
||||
|
||||
## Aliases
|
||||
- Munger
|
||||
- Charles Munger
|
||||
|
||||
## Overview
|
||||
Charlie Munger（1924–2023）是伯克希尔·哈撒韦副主席、巴菲特最重要的人生搭档，被誉为"最伟大的思想家之一"。他的核心方法论是"Mental Models"（心智模型网格）和"Inversion"（倒置法）——先想清楚如何失败再想如何成功。
|
||||
|
||||
## Core Method
|
||||
- **Mental Models Grid**：跨学科心智模型网格（物理学、经济学、心理学、工程学等），用多元框架理解世界
|
||||
- **Inversion**：先想清楚如何失败，然后避免它；"我唯一知道的就是我会死在哪里，这样我就永远不会去那里"
|
||||
- **Lollapalooza Effect**：当多个心智模型同时指向同一方向时，产生巨大的叠加效应
|
||||
|
||||
## Role in ZK Steward
|
||||
ZK Steward 在"商业策略"任务中切换到 Munger 视角，使用 mental models 和 inversion 进行多角度分析。
|
||||
|
||||
## Key Connections
|
||||
- [[ZK-Steward-Agent]] ← uses Munger perspective for business strategy tasks
|
||||
- [[Domain-Thinking]] ← Munger is the reference expert for business strategy domain
|
||||
- [[Luhmann-四原则]] ← Munger 的 mental models 网格与"避免过度结构化"存在张力（Munger 倾向预设框架）
|
||||
51
wiki/concepts/2D-First-Spatial-Second.md
Normal file
51
wiki/concepts/2D-First-Spatial-Second.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: "2D-First Spatial-Second"
|
||||
type: concept
|
||||
tags: []
|
||||
last_updated: 2026-03-05
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
2D-First Spatial-Second（2D 先行，空间渐进）是 [[nexus-spatial-discovery]] 定义的 [[Nexus Spatial]] 产品分阶段策略——先用高质量 2D Web 仪表盘建立市场，再渐进叠加空间计算能力，而非一开始就押注空间硬件。
|
||||
|
||||
## Strategic Rationale
|
||||
|
||||
**现实约束：**
|
||||
- Vision Pro 全球安装量仅约 100 万台，销量较峰值下跌 95%
|
||||
- 现有 AI Agent 编排工具用户已习惯 2D 工作流
|
||||
- 空间计算的学习曲线对早期采用者构成障碍
|
||||
|
||||
**市场机会：**
|
||||
- WebXR 已获得主流浏览器支持（Safari 2025 年底支持 WebXR Device API）
|
||||
- 2D → 2.5D → 3D 的渐进路径降低用户接受门槛
|
||||
- Web 平台可触达所有设备，无需额外硬件
|
||||
|
||||
## Three-Phase Roadmap
|
||||
|
||||
| 阶段 | 时间 | 产品形态 | 目标 |
|
||||
|------|------|---------|------|
|
||||
| **Phase 1** | 月 1–6 | 2D Web 仪表盘 + Three.js 2.5D | 50 个付费团队，$60K MRR |
|
||||
| **Phase 2** | 月 6–12 | WebXR 空间模式（可选） | 200 个团队，$300K MRR |
|
||||
| **Phase 3** | 月 12–18 | VisionOS 原生应用（按需） | 500 个团队，$1M+ MRR |
|
||||
|
||||
## Cross-Agent Consensus
|
||||
|
||||
该策略是 8 个专业 AI Agent **独立达成的一致结论**：
|
||||
- Product Trend Researcher：Vision Pro 市场数据不支持早期押注
|
||||
- Backend Architect：WebXR 是更合理的架构路径
|
||||
- Brand Guardian：2D 先行不影响空间品牌叙事
|
||||
- UX Researcher：渐进披露符合空间学习曲线
|
||||
- XR Interface Architect：WebXR 分发更广泛
|
||||
|
||||
## Key Tension
|
||||
|
||||
> **MVP scope**：Architecture（Phase 1 仅 2D）vs. Brand（演示需要强调空间价值）
|
||||
|
||||
**Resolution**：2D 先行，但所有 Demo 始终包含空间预览——用 2D 建立用户，用空间区分自己。
|
||||
|
||||
## Connections
|
||||
|
||||
- [[SpatialAIOps]] ← 战略框架
|
||||
- [[Nexus Spatial]] ← 落地产品
|
||||
- [[WebXR]] ← 技术基础
|
||||
42
wiki/concepts/4-Level-Semantic-Zoom.md
Normal file
42
wiki/concepts/4-Level-Semantic-Zoom.md
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: "4-Level Semantic Zoom"
|
||||
type: concept
|
||||
tags: []
|
||||
last_updated: 2026-03-05
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
4-Level Semantic Zoom（四层级语义缩放）是 [[nexus-spatial-discovery]] 中 [[Nexus Spatial]] 产品的导航范式——用户通过语义级别的缩放，在不同抽象层次间流畅切换，从全局舰队视角到单步执行追踪。
|
||||
|
||||
## Four Levels
|
||||
|
||||
| 层级 | 用户视角 | 信息密度 | 典型任务 |
|
||||
|------|---------|---------|---------|
|
||||
| **Fleet View**（舰队视图） | 所有工作流作为抽象形状 | 极低（颜色+状态） | 跨系统健康检查 |
|
||||
| **Workflow View**（工作流视图） | 节点图 + 标签 + 连接线 | 中等（拓扑结构） | 工作流设计/编辑 |
|
||||
| **Node View**（节点视图） | 扩展配置 + 近 I/O + 状态指标 | 高（单节点详情） | 节点调试/配置 |
|
||||
| **Trace View**（追踪视图） | 完整执行追踪 + 数据检查 | 极高（全链路数据） | 深度调试/根因分析 |
|
||||
|
||||
## Design Rationale
|
||||
|
||||
1. **语义对齐而非像素对齐**：缩放的是信息抽象层次，而非物理尺寸
|
||||
2. **与物理空间对应**：Fleet View → 远景（背景）→ Trace View → 近景（前景）
|
||||
3. **减少认知负荷**：用户始终看到"此刻需要关注的信息量"
|
||||
4. **过渡有目的**：每次缩放都是一次导航决策，而非平移
|
||||
|
||||
## Transition Choreography
|
||||
|
||||
| 过渡 | 时长 | 关键动作 |
|
||||
|------|------|---------|
|
||||
| Overview → Focus | 600ms | 相机漂移到目标，其他区域淡出至 30% |
|
||||
| Focus → Detail | 500ms | 节点滑出扩展，连接线高亮 |
|
||||
| Detail → Overview | 600ms | 面板收起，节点退后，全拓扑可见 |
|
||||
| Zone Switch | 500ms | 当前区域侧向滑出，新区域滑入 |
|
||||
| Window → Immersive | 1000ms | 边框溶解，节点展开至完整空间位置 |
|
||||
|
||||
## Connections
|
||||
|
||||
- [[SpatialAIOps]] ← 导航范式
|
||||
- [[Command-Theater]] ← 空间布局
|
||||
- [[Nexus Spatial]] ← 落地产品
|
||||
40
wiki/concepts/7-Layer-Harness-Stack.md
Normal file
40
wiki/concepts/7-Layer-Harness-Stack.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: "7-Layer Harness Stack"
|
||||
type: concept
|
||||
tags:
|
||||
- "harness-engineering"
|
||||
- "agentic-ai"
|
||||
- "system-design"
|
||||
sources:
|
||||
- "Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog"
|
||||
last_updated: 2026-04-20
|
||||
---
|
||||
|
||||
## Overview
|
||||
7层 Harness Stack——production-grade AI Agent 系统的分层架构规范，从认知层到约束恢复层的完整 7 层结构。
|
||||
|
||||
## Structure
|
||||
|
||||
| Layer | Name | Core Function |
|
||||
|-------|------|--------------|
|
||||
| 1 | Cognition | 受限操作边界，role file/job description |
|
||||
| 2 | Tools | 工具输出排序/去重/token 预算截断 |
|
||||
| 3 | Contracts & Interfaces | JSON Schema 边界验证，防 Schema Drift |
|
||||
| 4 | Orchestration | DAG/状态机约束允许的动作 |
|
||||
| 5 | Memory & State | Working Memory + Persistent State 分层 |
|
||||
| 6 | Evaluation & Observation | 异构验证（规则/工具/LLM-as-judge）|
|
||||
| 7 | Constraints & Recovery | 幂等重试，Context Reset 机制 |
|
||||
|
||||
## Principles
|
||||
- 模型在 Harness 内部，不直接对用户或外部世界说话
|
||||
- 每个边界交叉处有显式契约：严格 JSON Schema / 类型化函数签名 / 版本化 API spec
|
||||
- 每一层产生可被模型以外的东西验证的输出
|
||||
|
||||
## Related Concepts
|
||||
- [[Harness-Engineering]] — 父概念，本框架所属的工程学科
|
||||
- [[Context-Reset]] — 第 7 层 Constraints & Recovery 的关键机制
|
||||
- [[Sprint-Contract]] — 第 6 层 Evaluation 的关键机制
|
||||
- [[Schema-Drift]] — 第 3 层 Contracts 要解决的核心问题
|
||||
|
||||
## Source
|
||||
- [[Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog]]
|
||||
40
wiki/concepts/ABM-Display.md
Normal file
40
wiki/concepts/ABM-Display.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: "ABM Display"
|
||||
type: concept
|
||||
tags: ["abm", "b2b", "display", "account-based-marketing", "paid-media"]
|
||||
sources: ["paid-media-programmatic-buyer"]
|
||||
last_updated: 2026-04-26
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
ABM Display（Account-Based Display Advertising）是一种基于账户的展示广告策略，通过特定平台（Demandbase、6Sense、RollWorks 等）识别和定向目标企业账户，实现对特定公司决策者的精准触达。区别于传统基于人口统计或行为的展示广告，ABM Display 以企业账户为基本定向单元。
|
||||
|
||||
## Core Workflow
|
||||
|
||||
1. **Account List Upload**：上传目标企业账户列表（通常基于 CRM 数据）
|
||||
2. **Firmographic Enrichment**：通过 firmographic 数据（公司规模、行业、收入等）丰富账户画像
|
||||
3. **Intent Signal Processing**：利用意图数据（6Sense 等）识别主动研究解决方案的账户
|
||||
4. **Engagement Scoring**：对账户内的不同决策者进行参与度评分
|
||||
5. **CRM-to-Display Activation**：将评分结果激活到 DSP/ABM 平台进行定向投放
|
||||
6. **Cross-Channel Orchestration**：与销售团队协同，实现广告触达与销售跟进的时间协同
|
||||
|
||||
## Key Platforms
|
||||
|
||||
- **Demandbase**：基于 firmographic 的企业账户定向，覆盖 50+ B2B 数据维度
|
||||
- **6Sense**：意图数据和账户参与度评分，支持营销归因
|
||||
- **RollWorks**：经济实惠的 ABM 广告激活平台
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- **Reach Against Target**：目标账户列表触达率（目标 ≥60% 在活动期间触达）
|
||||
- **Engagement Depth**：账户内触达的决策者层级数量
|
||||
- **Pipeline Attribution**：90 天窗口内的正向管道归因
|
||||
|
||||
## Related Concepts
|
||||
- [[Programmatic Buying]]
|
||||
- [[Firmographic Targeting]]
|
||||
- [[Intent Data]]
|
||||
|
||||
## Sources
|
||||
- [[paid-media-programmatic-buyer]]
|
||||
50
wiki/concepts/ACOS.md
Normal file
50
wiki/concepts/ACOS.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: "ACOS"
|
||||
type: concept
|
||||
tags:
|
||||
- amazon
|
||||
- advertising
|
||||
- ppc
|
||||
- metrics
|
||||
- ecommerce
|
||||
sources:
|
||||
- marketing-cross-border-ecommerce
|
||||
last_updated: 2026-04-26
|
||||
---
|
||||
|
||||
## Aliases
|
||||
- ACOS
|
||||
- Advertising Cost of Sales
|
||||
- 广告成本占销售额比例
|
||||
|
||||
## Definition
|
||||
|
||||
ACOS（Advertising Cost of Sales，广告成本占销售额比例）是衡量亚马逊 PPC 广告效率的核心指标，计算公式为：`ACOS = 广告花费 / 广告带来的销售额 × 100%`。ACOS 越低，表示广告效率越高。
|
||||
|
||||
## Formula
|
||||
|
||||
```
|
||||
ACOS = (广告花费 / 广告带来的销售额) × 100%
|
||||
TACOS = 总广告花费（含站内外）/ 总销售额 × 100%
|
||||
```
|
||||
|
||||
## Interpretation
|
||||
|
||||
| ACOS 区间 | 含义 | 适用阶段 |
|
||||
|-----------|------|----------|
|
||||
| < 15% | 高效广告 | 成熟期产品，利润率充足的品类 |
|
||||
| 15-25% | 健康范围 | 成长期产品，平衡增长与利润 |
|
||||
| 25-35% | 可接受 | 新品推广期，侧重增长 |
|
||||
| > 35% | 需优化 | 超毛利率则必须关停或大幅调整 |
|
||||
|
||||
## Key Principles
|
||||
|
||||
- **ACOS 硬性底线**：任何超过毛利率的广告活动必须优化或关停
|
||||
- **TACOS < 10%**：成熟期产品目标，反映广告依赖度降低
|
||||
- **分阶段调控**：新品期允许高 ACOS 换增长，成熟期压低 ACOS 保利润
|
||||
- **负关键词策略**：持续否定非转化词，降低无效花费
|
||||
|
||||
## Connections
|
||||
- [[TACOS]] ← related_metric ← [[ACOS]]
|
||||
- [[Amazon Ads]] ← platform ← [[ACOS]] (measurement occurs within Amazon PPC)
|
||||
- [[Marketing Cross-Border E-Commerce Specialist]] ← uses ← [[ACOS]]
|
||||
@@ -1,38 +1,51 @@
|
||||
---
|
||||
title: "ADDIE 模型"
|
||||
type: concept
|
||||
tags: []
|
||||
last_updated: 2026-04-25
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
ADDIE 模型是企业培训课程开发的系统性框架，包含五个阶段：
|
||||
|
||||
1. **Analysis（分析）**：培训需求分析——组织诊断、能力差距识别、培训 ROI 估算、需求优先级排序
|
||||
2. **Design（设计）**：学习目标设计——基于 Bloom 认知分类定义可衡量的学习成果
|
||||
3. **Development（开发）**：课程内容开发——微课、案例、练习、题库、课件
|
||||
4. **Implementation（实施）**：培训交付——线上/线下/混合学习交付方式
|
||||
5. **Evaluation（评估）**：效果评估——基于 Kirkpatrick 四级模型评估培训效果
|
||||
|
||||
## Aliases
|
||||
- ADDIE
|
||||
- ADDIE Model
|
||||
- ADDIE 教学设计模型
|
||||
- 分析-设计-开发-实施-评估
|
||||
|
||||
## Key Characteristics
|
||||
|
||||
- **每个阶段有明确交付物**：分析报告、教学设计文档、课程包、培训执行计划、效果评估报告
|
||||
- **迭代性**：实践中通常循环迭代，而非严格线性执行
|
||||
- **系统性**：确保培训项目从需求到效果有完整闭环
|
||||
|
||||
## Related Concepts
|
||||
|
||||
- [[Kirkpatrick-四级评估]]：ADDIE 的最后一步（Evaluation）的具体方法论
|
||||
- [[Bloom-认知分类]]：ADDIE Design 阶段学习目标设计的认知层次框架
|
||||
- [[Kolb-体验式学习圈]]：与 ADDIE 并行的另一学习设计框架，侧重体验循环
|
||||
|
||||
## Source
|
||||
|
||||
- [[corporate-training-designer]]
|
||||
---
|
||||
title: "ADDIE Model"
|
||||
type: concept
|
||||
tags: [instructional-design, learning-theory]
|
||||
sources: [corporate-training-designer]
|
||||
last_updated: 2026-05-29
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
ADDIE 模型是企业教学设计（Instructional Systems Design, ISD）的经典五阶段框架，代表 **Analysis（分析）→ Design（设计）→ Development（开发）→ Implementation（实施）→ Evaluation（评估）** 五个阶段，每阶段有明确的输入/输出交付物。
|
||||
|
||||
## Phases
|
||||
|
||||
### A — Analysis（分析）
|
||||
- 组织诊断：战略解码、业务痛点映射、人才盘点
|
||||
- 能力差距分析：建立岗位胜任力模型（知识/技能/态度），通过360度评估、绩效数据、主管访谈定位能力缺口
|
||||
- 培训 ROI 估算：基于业务指标（人均生产力、质量合格率、客户满意度等）估算培训投资回报
|
||||
- 需求优先级：紧迫性×重要性矩阵——区分"必须培训"、"应该培训"和"可自学"
|
||||
|
||||
### D — Design（设计）
|
||||
- 选择教学策略和学习形式（线上/线下/混合）
|
||||
- 设计课程大纲和学习路径
|
||||
- 准备培训计划、讲师安排、场地和材料需求
|
||||
- 准备培训预算
|
||||
|
||||
### D — Development（开发）
|
||||
- 访谈主题专家，萃取关键知识和经验
|
||||
- 开发课件、案例、练习和评估题库
|
||||
- 内部评审和试讲——收集反馈并迭代
|
||||
|
||||
### I — Implementation（实施）
|
||||
- 训前：学员通知、预习任务推送、学习平台配置
|
||||
- 训中：课堂授课、互动管理、实时学习效果检查
|
||||
- 训后：作业布置、行动计划制定、学习社群建立
|
||||
|
||||
### E — Evaluation（评估）
|
||||
- 收集培训满意度和学习评估数据
|
||||
- 追踪训后行为改变和业务指标变化
|
||||
- 产出培训效果报告和改进建议
|
||||
- 固化最佳实践，更新课程资源库
|
||||
|
||||
## Key Principles
|
||||
- **阶段门控（Gate）**：每个阶段完成后必须通过评审才能进入下一阶段，确保质量
|
||||
- **迭代性**：在实际项目（尤其是快速迭代场景）可与 [[SAM-Model]] 混合使用
|
||||
- **以终为始**：从评估阶段开始反向设计（Backward Design），确保所有学习活动都指向可测量的目标
|
||||
|
||||
## Connections
|
||||
- [[ADDIE-Model]] ← foundational_model ← [[SAM-Model]]（SAM 是 ADDIE 的快速迭代变体，适合敏捷场景）
|
||||
- [[Bloom-Taxonomy]] ← learning_objective_framework ← [[ADDIE-Model]]（ADDIE 的设计阶段使用 Bloom 分类定义学习目标）
|
||||
- [[Kirkpatrick-Model]] ← evaluation_framework ← [[ADDIE-Model]]（ADDIE 的 E 阶段通常采用 Kirkpatrick 四级评估）
|
||||
|
||||
55
wiki/concepts/AI-For-On-Call.md
Normal file
55
wiki/concepts/AI-For-On-Call.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: "AI For On-Call"
|
||||
type: concept
|
||||
tags: [sre, ai, on-call, incident-response, automation]
|
||||
last_updated: 2026-04-20
|
||||
---
|
||||
|
||||
# AI For On-Call
|
||||
|
||||
AI 在值班（On-Call）场景中的最佳应用不是自主修复，而是为值班工程师提供足够的上下文以快速修复故障。
|
||||
|
||||
## Core Thesis
|
||||
> "AI's most valuable role in SRE isn't autonomous remediation. It's making sure on-call engineers have the context to fix incidents fast." — Heinrich Hartmann
|
||||
|
||||
## Why Context Matters
|
||||
值班工程师在面对故障时最大的挑战不是不知道怎么做，而是：
|
||||
1. **信息过载**：日志、指标、告警太多，难以快速定位问题
|
||||
2. **上下文丢失**：不熟悉的服务/代码，需要时间理解
|
||||
3. **时间压力**：MTTR 目标要求快速响应
|
||||
|
||||
## AI 辅助 On-Call 的关键场景
|
||||
|
||||
### 1. 上下文聚合（Context Aggregation）
|
||||
AI 从多个来源聚合相关信息：
|
||||
- 告警历史和趋势
|
||||
- 相关的故障报告
|
||||
- 最近变更记录
|
||||
- 依赖服务状态
|
||||
|
||||
### 2. 快速诊断辅助（Rapid Diagnosis）
|
||||
- 总结告警的根本原因
|
||||
- 推荐可能有效的修复步骤
|
||||
- 识别类似的已知问题
|
||||
|
||||
### 3. 值班交接增强（On-Call Handoff）
|
||||
- 自动生成值班交接摘要
|
||||
- 突出显示未解决的问题
|
||||
- 提供历史上下文
|
||||
|
||||
## What AI Should NOT Do
|
||||
- **自动执行修复**：缺乏足够上下文的自动修复可能造成更大损害
|
||||
- **绕过人工审批**：关键变更需要人工确认
|
||||
- **忽视不确定性**：AI 应清楚表达置信度
|
||||
|
||||
## Related Products
|
||||
- [[RunLLM]]：专注于 On-Call 上下文增强的 AI 产品
|
||||
|
||||
## Related Concepts
|
||||
- [[Incident-Response]]
|
||||
- [[Observability]]
|
||||
- [[Resilience]]
|
||||
- [[Self-Healing]]
|
||||
|
||||
## Source
|
||||
- SRE Weekly Issue #513 — [[sre-weekly-issue-513]]
|
||||
@@ -1,39 +1,25 @@
|
||||
---
|
||||
title: "AWS Secrets Manager"
|
||||
type: concept
|
||||
tags:
|
||||
- AWS
|
||||
- Secrets-Management
|
||||
- Security
|
||||
last_updated: 2026-04-14
|
||||
---
|
||||
|
||||
## Definition
|
||||
AWS Secrets Manager 是 AWS 提供的完全托管式密钥管理服务，用于安全存储和检索应用程序、服务和 IT 资源的密钥。
|
||||
|
||||
## Core Features
|
||||
- **内置数据库集成**：开箱即用支持 AWS RDS、Redshift、DynamoDB 等服务的密钥管理
|
||||
- **高可用与 DR**：托管服务自动实现跨可用区高可用和灾难恢复
|
||||
- **按用量计费**：基于 API 调用次数计费，无需预付成本
|
||||
- **自动密钥轮换**：通过 Lambda 函数实现数据库凭证自动轮换
|
||||
- **IAM 访问控制**：通过 IAM 角色和标签实现精细化权限管理
|
||||
- **账户级管理**：AWS 在账户级别管理密钥，可降低成本并提升安全性
|
||||
|
||||
## Evaluation vs HashiCorp Vault
|
||||
| 维度 | AWS Secrets Manager | HashiCorp Vault |
|
||||
|------|---------------------|-----------------|
|
||||
| 部署模式 | 完全托管 | 自托管 |
|
||||
| 云厂商 | AWS 原生 | 云厂商无关 |
|
||||
| 成本模型 | 按用量计费 | 按用户数收费 |
|
||||
| 高可用 | 内置 | 企业版才支持 |
|
||||
| 动态密钥 | 支持 | 支持 |
|
||||
| 证书签名 | 不支持原生 | 支持嵌入式签名 |
|
||||
| 实施复杂度 | 简单易用 | 需要专业知识 |
|
||||
|
||||
## Implementation Phases
|
||||
1. **试点阶段（30天）**：验证开箱即用功能，识别缺失功能（SSH 密钥轮换、用户密码轮换）
|
||||
2. **实施阶段**：从 Control Tower 开始，从 CI/CD 流程中清除明文密码和密钥，集中化管理
|
||||
|
||||
## Sources
|
||||
- [[ctp-topic-37-secrets-certificates-management]]（选型评估）
|
||||
- [[ctp-topic-62-aws-secrets-manager]]（企业级深度实践）
|
||||
---
|
||||
title: "AWS Secrets Manager"
|
||||
type: concept
|
||||
tags:
|
||||
- AWS
|
||||
- Secrets Management
|
||||
- Security
|
||||
sources:
|
||||
- ctp-topic-12-using-ses-smtp-service-terraform-module
|
||||
- ctp-topic-62-aws-secrets-manager
|
||||
last_updated: 2026-04-14
|
||||
---
|
||||
|
||||
## Definition
|
||||
AWS Secrets Manager 是一项 AWS 服务，用于安全存储和检索敏感信息（如数据库凭证、API 密钥、SMTP 认证信息），支持自动轮换和精细的 IAM 访问控制。
|
||||
|
||||
## Key Use Cases
|
||||
- 存储 SES SMTP 认证信息（IAM 用户 Access Key / Secret Key 转换后的用户名和密码）
|
||||
- Oracle DB 用户密码自动轮换（Lambda 函数连接 Oracle 实例执行轮换）
|
||||
- SendGrid API 密钥集中管理
|
||||
|
||||
## Connections
|
||||
- [[CTP Topic 12 Using SES SMTP service terraform module]] — SES SMTP 凭证存储方案
|
||||
- [[CTP Topic 62 AWS Secrets Manager]] — 深度实践与标准文档
|
||||
- [[VPC Endpoint]] — 配合使用实现凭证的安全私有访问
|
||||
|
||||
82
wiki/concepts/Access-Control.md
Normal file
82
wiki/concepts/Access-Control.md
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: "Access Control（访问控制）"
|
||||
type: concept
|
||||
tags: [blockchain, security, smart-contract, access-control]
|
||||
sources: [blockchain-security-auditor]
|
||||
last_updated: 2026-05-30
|
||||
---
|
||||
|
||||
## Aliases
|
||||
- Access Control
|
||||
- 访问控制 / 权限控制
|
||||
|
||||
## Definition
|
||||
|
||||
访问控制（Access Control）定义谁可以执行合约中的哪些操作。访问控制缺陷是智能合约最常见的高危漏洞类别之一，错误的权限配置可直接导致资金被盗或协议被永久阻塞。
|
||||
|
||||
## Key Vulnerability Classes
|
||||
|
||||
### 1. Missing Access Modifier（缺失访问修饰符）
|
||||
```solidity
|
||||
// VULNERABLE: withdraw() 没有访问控制，任何人都能调用
|
||||
function withdraw() external {
|
||||
uint256 amount = balances[msg.sender];
|
||||
(bool success,) = msg.sender.call{value: amount}("");
|
||||
require(success);
|
||||
balances[msg.sender] = 0;
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Wrong Access Modifier（错误的访问修饰符）
|
||||
```solidity
|
||||
// VULNERABLE: 应该是 onlyOwner，但误写成 external
|
||||
// 导致任何人都能调用紧急停止
|
||||
function emergencyStop() external {
|
||||
paused = true;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Unprotected initialization（未保护的初始化）
|
||||
```solidity
|
||||
// VULNERABLE: initialize() 没有 initializer 修饰符
|
||||
// 攻击者可抢先调用，劫持合约
|
||||
function initialize(address _owner) external {
|
||||
owner = _owner;
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Proxy Storage Collision（代理存储冲突）
|
||||
升级型代理合约中，新实现版本的存储布局与旧版本不兼容，导致状态变量被覆盖：
|
||||
```solidity
|
||||
// Implementation V1
|
||||
uint256 public totalValue; // slot 0
|
||||
|
||||
// Implementation V2 — 新增变量导致 slot 0 被覆盖
|
||||
address public newAdmin; // slot 0 ← 覆盖了 totalValue！
|
||||
uint256 public totalValue; // slot 1
|
||||
```
|
||||
|
||||
### 5. Role Renunciation Hijack（角色放弃劫持）
|
||||
允许 admin 放弃角色后无人能恢复，导致协议永久不可升级。
|
||||
|
||||
## Audit Checklist
|
||||
|
||||
- [ ] 所有特权函数都有显式访问修饰符
|
||||
- [ ] Admin 角色不能自我授予（需要多签或时间锁）
|
||||
- [ ] `initialize()` 只能调用一次（initializer 修饰符）
|
||||
- [ ] 实现合约构造函数中有 `_disableInitializers()`
|
||||
- [ ] `_authorizeUpgrade()` 受 owner/多签/时间锁保护
|
||||
- [ ] 存储布局在版本间兼容（无 slot 碰撞）
|
||||
- [ ] 无 `delegatecall` 到用户可控地址
|
||||
|
||||
## Severity Classification
|
||||
|
||||
- **Critical**：缺失关键特权函数的访问控制，可直接导致资金损失
|
||||
- **High**：条件性权限提升（需要特定状态），或协议可被 admin 永久阻塞
|
||||
- **Medium**：缺失非关键函数的访问控制
|
||||
- **Low**：缺少事件日志、代码规范问题
|
||||
|
||||
## Related Concepts
|
||||
- [[Reentrancy]]：缺失访问控制会加剧重入攻击影响
|
||||
- [[Proxy-Upgrade]]：代理升级模式引入额外访问控制风险
|
||||
- [[OpenZeppelin]] 的 AccessControl 库是标准安全实现
|
||||
59
wiki/concepts/Account-Reconciliation.md
Normal file
59
wiki/concepts/Account-Reconciliation.md
Normal file
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: "Account Reconciliation"
|
||||
type: concept
|
||||
tags: [finance, accounting]
|
||||
sources: [finance-bookkeeper-controller]
|
||||
last_updated: 2026-05-02
|
||||
---
|
||||
|
||||
## Definition
|
||||
账户调节（Account Reconciliation）是将总账（GL）余额与支持明细或分账余额进行核对的流程，确保每个账户的余额准确、完整、有据可查。
|
||||
|
||||
## Purpose
|
||||
- 检测和纠正错误
|
||||
- 确保财务信息的准确性
|
||||
- 满足审计要求
|
||||
- 发现异常或欺诈信号
|
||||
|
||||
## Core Template Structure
|
||||
|
||||
### Balance Summary
|
||||
| Source | Amount |
|
||||
|--------|--------|
|
||||
| GL Balance (per trial balance) | $[X] |
|
||||
| Reconciliation Balance (per supporting detail) | $[X] |
|
||||
| **Difference** | **$[X]** |
|
||||
|
||||
### Reconciling Items
|
||||
记录所有待处理差异，包括日期、描述、金额、状态和解决日期。
|
||||
|
||||
### Adjusted Balance
|
||||
| Item | Amount |
|
||||
|------|--------|
|
||||
| GL Balance | $[X] |
|
||||
| + Reconciling Items | $[X] |
|
||||
| **Reconciled Balance** | **$[X]** |
|
||||
| Subledger / Support Balance | **$[X]** |
|
||||
| **Variance** | **$0** |
|
||||
|
||||
## Common Reconciliation Types
|
||||
- 银行账户调节
|
||||
- 信用卡调节
|
||||
- AR aging 与 GL 核对
|
||||
- AP aging 与 GL 核对
|
||||
- 预付账款与摊销计划
|
||||
- 固定资产与折旧
|
||||
- 递延收入滚动表
|
||||
- 关联方交易调节
|
||||
- 权益变动调节
|
||||
- 工资税负债与申报表
|
||||
|
||||
## Core Principle
|
||||
> "Reconciliation is not a chore — it's a detective process. Every unreconciled difference is a story waiting to be understood."
|
||||
> — Dana, Bookkeeper & Controller Agent
|
||||
|
||||
## Related Concepts
|
||||
- [[Month-End-Close-Process]]
|
||||
- [[Journal Entry]]
|
||||
- [[Internal Controls]]
|
||||
- [[Audit Readiness]]
|
||||
@@ -1,38 +1,52 @@
|
||||
---
|
||||
title: "Account Architecture"
|
||||
type: concept
|
||||
tags: ["paid-media", "google-ads", "strategy", "structure"]
|
||||
last_updated: 2026-04-20
|
||||
---
|
||||
|
||||
## Aliases
|
||||
- Account Structure
|
||||
- Campaign Architecture
|
||||
- Google Ads Structure
|
||||
|
||||
## Overview
|
||||
账户架构是 [[PaidMediaPpcStrategist]] 的核心理念：将整个广告账户视为一个系统，而非关键词和出价的简单集合。活动、广告组、受众、信号协同工作以驱动业务成果。
|
||||
|
||||
## Key Components
|
||||
- **Campaign Structure**: 活动层级，定义预算、地理位置、受众、出价策略
|
||||
- **Ad Group Taxonomy**: 广告组分类，结构化组织关键词和受众
|
||||
- **Label Systems**: 标签系统，用于分类管理和自动化规则
|
||||
- **Naming Conventions**: 命名规范，确保规模化运营的可读性和可维护性
|
||||
|
||||
## Best Practices (PPC Strategist)
|
||||
- 活动之间应隔离预算和目标，避免内耗
|
||||
- 广告组应保持主题一致性
|
||||
- 广泛匹配关键词配合智能竞价是规模化增长的核心
|
||||
- 负关键词架构防止无效流量侵蚀预算
|
||||
- 账户层级与 MCC（多账户管理）策略配合
|
||||
|
||||
## Tiered Campaign Architecture
|
||||
- **Brand**: 品牌词保护，高转化，低成本
|
||||
- **Non-Brand**: 非品牌词，规模化增长的核心
|
||||
- **Competitor**: 竞品词，主动触达竞品用户
|
||||
- **Conquest**: 征服策略，针对高价值竞品用户
|
||||
|
||||
## Related Concepts
|
||||
- [[TieredCampaignArchitecture]]: 分层活动架构的具体实现
|
||||
- [[SmartBidding]]: 账户架构中出价策略的选择
|
||||
- [[NegativeKeyword]]: 负关键词是账户架构的重要组成部分
|
||||
---
|
||||
title: "Account Architecture"
|
||||
type: concept
|
||||
tags: ["ppc", "account-structure", "google-ads", "enterprise", "paid-media"]
|
||||
sources: ["paid-media-ppc-strategist"]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
账户架构（Account Architecture）是 PPC 广告账户的层级结构设计，包括 Campaign（广告系列）→ Ad Group（广告组）→ Keywords/Ads（关键词/广告）的完整层级体系，以及命名规范、标签系统、账户政策等辅助管理机制。核心理念：**账户架构即战略**（account structure as strategy）——而非单纯的关键词和出价管理。
|
||||
|
||||
## Core Components
|
||||
|
||||
### Account Level
|
||||
- **账户设置**：时区、货币、跳转追踪域名
|
||||
- **转化追踪**：Conversion Actions 配置（主/次、微/宏转化）
|
||||
- **用户权限**：多用户协作和访问级别
|
||||
|
||||
### Campaign Level
|
||||
- **广告系列类型**：Search / Shopping / Performance Max / Demand Gen / Display / Video
|
||||
- **预算**：日预算或总预算
|
||||
- **地理定向**：国家/地区/DMA/城市级别定向
|
||||
- **语言定向**：受众语言
|
||||
- **投放时间**：Schedule 设置
|
||||
- **竞价策略**：Manual CPC / Automated Bidding
|
||||
|
||||
### Ad Group Level
|
||||
- **关键词主题**：围绕单一主题/产品/意图的关键词分组
|
||||
- **广告变体**：同一广告组内多个广告文案轮播测试
|
||||
- **受众定向**：广告组级受众叠加
|
||||
|
||||
## Naming Conventions at Scale
|
||||
|
||||
支持数百个广告系列的命名规范示例：
|
||||
```
|
||||
{{Channel}}-{{Region}}-{{ProductLine}}-{{CampaignType}}-{{MatchType}}
|
||||
# 例如：
|
||||
SEA-US-Software-Competitor-Exact
|
||||
PMX-GLOBAL-Brand-Awareness-Broad
|
||||
```
|
||||
|
||||
## Label System
|
||||
|
||||
- **颜色标签**：按产品线/优先级/状态分类
|
||||
- **过滤器**：跨广告系列/广告组的灵活筛选
|
||||
- **脚本自动化**：通过 Labels + Scripts 实现批量操作
|
||||
|
||||
## Connections
|
||||
- [[TieredCampaignArchitecture]]：Account Architecture 的具体实现模式
|
||||
- [[GoogleAds]]：Account Architecture 的主要操作平台
|
||||
- [[PerformanceMax]]：与标准广告系列结构不同的 AI 驱动架构
|
||||
|
||||
42
wiki/concepts/ActorReplication.md
Normal file
42
wiki/concepts/ActorReplication.md
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: "Actor Replication"
|
||||
type: concept
|
||||
tags: ["unreal-engine", "networking", "multiplayer"]
|
||||
sources: ["unreal-multiplayer-architect", "unreal-multiplayer-architect"]
|
||||
last_updated: 2026-04-30
|
||||
---
|
||||
|
||||
## Aliases
|
||||
- Actor 复制
|
||||
- 属性复制
|
||||
- Property Replication
|
||||
|
||||
## 定义
|
||||
Actor 复制是 UE5 中将服务器端 Actor 状态同步到客户端的核心网络机制。通过 `UPROPERTY(Replicated)` 声明需要复制的属性。
|
||||
|
||||
## 复制条件
|
||||
- `Replicated`: 无条件复制到所有相关客户端
|
||||
- `ReplicatedUsing=OnRep_Function`: 复制时触发 RepNotify 回调
|
||||
- `DOREPLIFETIME_CONDITION`: 按条件复制（如 `COND_OwnerOnly`、`COND_SimulatedOnly`）
|
||||
|
||||
## 生命周期
|
||||
1. 服务器模拟游戏逻辑，更新 Actor 属性
|
||||
2. UE5 复制层检测属性变化
|
||||
3. 按 `NetUpdateFrequency` 打包更新
|
||||
4. 通过网络传输到客户端
|
||||
5. 客户端应用更新，触发 RepNotify（如果有）
|
||||
|
||||
## 关键配置
|
||||
- `NetUpdateFrequency`: 更新频率（默认 100Hz，通常过高）
|
||||
- `MinNetUpdateFrequency`: 最小更新频率
|
||||
- `GetNetPriority()`: 优先级，靠近/可见的 Actor 优先级更高
|
||||
|
||||
## 优化策略
|
||||
- Replication Graph 空间分区
|
||||
- 条件复制减少带宽
|
||||
- 按 Actor 类型设置差异化频率
|
||||
|
||||
## 相关概念
|
||||
- [[Server-Authoritative Model]] — 复制背后的权威模型
|
||||
- [[Replication Graph]] — 复制优化框架
|
||||
- [[GAS (Gameplay Ability System)]] — 基于复制的能力系统
|
||||
62
wiki/concepts/Agent-Collaboration-Protocol.md
Normal file
62
wiki/concepts/Agent-Collaboration-Protocol.md
Normal file
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: "Agent Collaboration Protocol"
|
||||
type: concept
|
||||
tags: []
|
||||
last_updated: 2026-05-02
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
规范化多 Agent 协作流程——定义何时发起协作、协作内容模板、协作边界及交接合同。
|
||||
|
||||
## Overview
|
||||
|
||||
在多 Agent 系统中，不同 Agent 负责不同专业领域。Agent Collaboration Protocol 为每个协作节点定义标准化协议，确保信息传递完整、意图清晰、交接无遗漏。
|
||||
|
||||
## Core Components
|
||||
|
||||
### 协作发起时机
|
||||
- 交接点：当前 Agent 工作完成后、需要下游 Agent 承接时
|
||||
- 依赖点：当前 Agent 需要上游 Agent 输出时
|
||||
- 冲突点：发现超出自身职责范围的问题时
|
||||
- 安全点：涉及凭证/密钥/认证等安全敏感操作时
|
||||
|
||||
### 协作内容模板
|
||||
每个协作请求必须包含：
|
||||
1. **上下文摘要**：工作进展和已完成内容
|
||||
2. **具体请求**：需要对方完成什么
|
||||
3. **交付物格式**：期望的输出格式和结构
|
||||
4. **约束条件**：时间限制、质量标准、特殊要求
|
||||
5. **交接合同**：交接数据的 schema 定义
|
||||
|
||||
### 协作边界
|
||||
- 不越权：不在自身职责外做决策
|
||||
- 不兜底：发现超出范围的问题时立即上报，而非自行处理
|
||||
- 不丢失：每次协作记录到 log.md，确保可追溯
|
||||
|
||||
## Workflow Architect 中的协作协议
|
||||
|
||||
| 协作方 | 时机 | 内容 | 交付物 |
|
||||
|--------|------|------|--------|
|
||||
| [[Reality-Checker]] | Draft spec 完成后、标记 Review 前 | 规范与实际代码差距验证 | Reality Checker Findings 表 |
|
||||
| [[Backend-Architect]] | 发现实现缺陷时 | 补充缺失逻辑（重试/错误处理） | 修复代码 |
|
||||
| [[Security-Engineer]] | 涉及凭证/密钥/认证/API 调用时 | 凭证传递机制安全性审查 | 安全评估意见 |
|
||||
| [[API-Tester]] | Spec 标记 Approved 后 | 生成全部测试用例 | 自动化测试脚本 |
|
||||
| [[DevOps-Automator]] | 揭示基础设施销毁顺序需求时 | 验证 IaC 销毁顺序 | 销毁顺序确认 |
|
||||
|
||||
## Key Principles
|
||||
|
||||
- **主动发起**：发现需要协作时立即发起，不等待
|
||||
- **标准化模板**：每次协作使用统一格式，减少理解成本
|
||||
- **明确边界**：知道自己不做什么，比知道自己做什么更重要
|
||||
- **完整交接**：交接内容包括所有上下文，而非仅最终结果
|
||||
|
||||
## Related Concepts
|
||||
- [[Handoff-Contract]]：协作交接的数据 schema 定义
|
||||
- [[Reality-Checker]]：Workflow Architect 的首个强制协作节点
|
||||
- [[Workflow-Tree-Spec]]：协作产出的主要载体
|
||||
|
||||
## Aliases
|
||||
- Multi-Agent Handoff Protocol
|
||||
- Agent Coordination Framework
|
||||
- Inter-Agent Collaboration Standard
|
||||
32
wiki/concepts/Agent-Collapse.md
Normal file
32
wiki/concepts/Agent-Collapse.md
Normal file
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: "Agent Collapse"
|
||||
type: concept
|
||||
tags:
|
||||
- "agentic-ai"
|
||||
- "failure-mode"
|
||||
- "context-window"
|
||||
sources:
|
||||
- "Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog"
|
||||
last_updated: 2026-04-20
|
||||
---
|
||||
|
||||
## Overview
|
||||
Agent Collapse（10-Step Collapse）——AI Agent 在多步任务执行过程中逐渐崩溃的现象，典型表现为步骤 1-3 正常执行，步骤 7 开始幻觉数据，步骤 10 输出损坏的 JSON 或崩溃。
|
||||
|
||||
## Root Causes
|
||||
- **Context window 静默截断**：工具输出超出上下文窗口后被静默截断，模型感知不到数据丢失
|
||||
- **无 Schema 验证**：LLM 输出的字段类型漂移（price 从 float 变为 string），下游管道静默产生垃圾数据
|
||||
- **无状态管理**：context window 是易失的，关键状态（如 pending/in-progress/completed 标记）随上下文重置丢失
|
||||
- **无幂等重试**：单步失败导致整个管道重启，而非精确重试失败步骤
|
||||
|
||||
## Manifestation Example
|
||||
> 部署一个自主 Agent 编写市场研究报告。步骤 1-3 完美执行：计划任务 → 搜索网页 → 提取竞品数据。步骤 7 开始幻觉统计数据（因为搜索工具 payload 超出上下文窗口被静默截断）。步骤 10 输出损坏的 JSON 字符串（因为管道中没有 Schema 验证器）。
|
||||
|
||||
## Solutions
|
||||
- [[Harness-Engineering]]：系统性地为每个失效点增加防护层
|
||||
- [[State-Externalization]]：将任务状态写入磁盘，不依赖 context window
|
||||
- [[Schema-Drift]] 防护：每个 LLM 输出必须经过 JSON Schema 验证
|
||||
- [[Idempotency]]：单步失败只重试该步，不重启管道
|
||||
|
||||
## Source
|
||||
- [[Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog]]
|
||||
39
wiki/concepts/Agent-Handoff.md
Normal file
39
wiki/concepts/Agent-Handoff.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: "Agent Handoff"
|
||||
type: concept
|
||||
tags: [multi-agent, coordination, handoff, nexus]
|
||||
sources: [executive-brief, quickstart, workflow-with-memory]
|
||||
last_updated: 2026-05-01
|
||||
aliases:
|
||||
- Agent Handoff Protocol
|
||||
- Structured Handoff
|
||||
- Context Continuity
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Agent 交接（Agent Handoff）—— 多 Agent 工作流中从一个 Agent 交付物传递到下一个 Agent 的结构化上下文传递协议，确保接收 Agent 获得完整的执行上下文，避免冷启动和重复劳动。
|
||||
|
||||
## Core Problem
|
||||
|
||||
**交接边界失败率：73%** —— 当 Agent 缺乏结构化协调协议时，多 Agent 项目在交接边界处的失败率高达 73%，表现为：
|
||||
- 上下文丢失（交接时未传递关键决策和中间产物）
|
||||
- 重复劳动（下一个 Agent 重复上一个 Agent 已完成的工作）
|
||||
- 质量缺口（上一个 Agent 的缺陷传递到下一个 Agent）
|
||||
|
||||
## Structured Handoff Components
|
||||
|
||||
一份完整的 Agent 交接应包含：
|
||||
|
||||
1. **交付物清单**：明确列出发交给下一 Agent 的所有文件和产出
|
||||
2. **上下文摘要**：用 3-5 句话总结当前状态和已完成的关键决策
|
||||
3. **下一步指令**：清楚描述下一 Agent 需要完成的具体任务
|
||||
4. **质量证据**：提供可验证的质量证明（测试截图/性能数据/设计评审通过记录）
|
||||
5. **风险标记**：标注已知的限制条件和潜在风险
|
||||
|
||||
## Related Concepts
|
||||
|
||||
- [[Handoff Boundary]]：交接的边界点，即失败率最高的 73% 失败发生处
|
||||
- [[Evidence Over Claims]]：交接内容必须包含可验证的证据，而非口头承诺
|
||||
- [[Quality Gate]]：交接后需通过质量门控验证才能推进
|
||||
- [[Memory-Based-Handoff]]：通过 MCP Memory Server 实现自动化的 Agent 交接机制
|
||||
33
wiki/concepts/Agent-Orchestration.md
Normal file
33
wiki/concepts/Agent-Orchestration.md
Normal file
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: "Agent-Orchestration"
|
||||
type: concept
|
||||
tags: []
|
||||
---
|
||||
|
||||
## Definition
|
||||
Agent 编排（Agent Orchestration）是指通过工作流引擎统一协调和调度多个 AI Agent，使它们协同工作完成复杂任务的管理模式。
|
||||
|
||||
## Key Patterns
|
||||
- **集中式编排**：单一工作流引擎（n8n）控制多个 Agent 的调用顺序和数据流转
|
||||
- **并行调用**：同一工作流中同时调用多个 Agent（如 Hermes + OpenClaw）
|
||||
- **条件路由**：根据前一个 Agent 的输出决定调用哪个 Agent
|
||||
|
||||
## n8n 编排架构示例
|
||||
```
|
||||
n8n Workflow
|
||||
├─ Trigger (Telegram/Email/Webhook...)
|
||||
├─ HTTP Request Node 1 → Hermes Agent (port 8642)
|
||||
├─ HTTP Request Node 2 → OpenClaw Agent (port 18789)
|
||||
└─ Output Node (Telegram/File/Email...)
|
||||
```
|
||||
|
||||
## 优势
|
||||
- **统一入口**：用户通过单一界面与多个 Agent 交互
|
||||
- **数据流转**：一个 Agent 的输出可直接作为另一个 Agent 的输入
|
||||
- **可观测性**：工作流引擎提供执行日志和状态追踪
|
||||
- **灵活性**：可随时增删 Agent，不影响整体架构
|
||||
|
||||
## Related
|
||||
- [[n8n]] 是本 Wiki 中记录的编排工具
|
||||
- [[Hermes-Agent]] 和 [[OpenClaw]] 是被编排的 Agent 示例
|
||||
- [[OpenAI-Compatible-API]] 是连接 Agent 的标准接口
|
||||
@@ -1,77 +1,77 @@
|
||||
---
|
||||
title: "Agent Template"
|
||||
type: concept
|
||||
tags: [multi-agent, agent-design, the-agency]
|
||||
sources: [contributing_zh-cn, contributing-to-the-agency]
|
||||
last_updated: 2026-04-24
|
||||
---
|
||||
|
||||
# Agent Template
|
||||
|
||||
The standardized YAML frontmatter + structured document template for creating The Agency agents.
|
||||
|
||||
## YAML Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: Agent Name
|
||||
description: One-sentence description of agent's specialty and positioning
|
||||
color: Color Name or "#hex-value"
|
||||
---
|
||||
```
|
||||
|
||||
## Document Structure
|
||||
|
||||
### 🧠 Identity & Memory
|
||||
- **Role**: Clear role description
|
||||
- **Personality**: Personality traits and communication style
|
||||
- **Memory**: What the agent needs to remember and learn
|
||||
- **Experience**: Domain expertise and perspective
|
||||
|
||||
### 🎯 Core Mission
|
||||
- Core Responsibility 1 (with clear deliverables)
|
||||
- Core Responsibility 2 (with clear deliverables)
|
||||
- Core Responsibility 3 (with clear deliverables)
|
||||
- **Default Requirement**: Always follow best practices
|
||||
|
||||
### 🚨 Critical Rules
|
||||
Domain-specific rules and constraints that define how the agent operates.
|
||||
|
||||
### 📋 Technical Deliverables
|
||||
Concrete outputs the agent produces:
|
||||
- Code examples
|
||||
- Templates
|
||||
- Frameworks
|
||||
- Documentation
|
||||
|
||||
### 🔄 Workflow
|
||||
Step-by-step process the agent follows:
|
||||
1. Phase 1: Exploration & Research
|
||||
2. Phase 2: Planning & Strategy
|
||||
3. Phase 3: Execution & Implementation
|
||||
4. Phase 4: Review & Optimization
|
||||
|
||||
### 💭 Communication Style
|
||||
- How the agent communicates
|
||||
- Example phrases and expression patterns
|
||||
- Tone and style
|
||||
|
||||
### 🔄 Learning & Memory
|
||||
What the agent continuously learns from:
|
||||
- Success patterns
|
||||
- Failure cases
|
||||
- User feedback
|
||||
- Domain evolution
|
||||
|
||||
### 🎯 Success Metrics
|
||||
Quantifiable outcomes:
|
||||
- Quantitative metrics (with specific values)
|
||||
- Qualitative metrics
|
||||
- Performance benchmarks
|
||||
|
||||
### 🚀 Advanced Capabilities
|
||||
Advanced techniques and methods the agent masters.
|
||||
|
||||
## Connections
|
||||
- Implements [[Agent-Design-Principles]] — structural template for the five design principles
|
||||
- Used in [[Multi-Agent-Team]] — standardized agent creation
|
||||
---
|
||||
title: "Agent Template"
|
||||
type: concept
|
||||
tags: [multi-agent, agent-design, the-agency]
|
||||
sources: [contributing_zh-cn, contributing, contributing-to-the-agency]
|
||||
last_updated: 2026-04-27
|
||||
---
|
||||
|
||||
# Agent Template
|
||||
|
||||
The standardized YAML frontmatter + structured document template for creating The Agency agents.
|
||||
|
||||
## YAML Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: Agent Name
|
||||
description: One-sentence description of agent's specialty and positioning
|
||||
color: Color Name or "#hex-value"
|
||||
---
|
||||
```
|
||||
|
||||
## Document Structure
|
||||
|
||||
### 🧠 Identity & Memory
|
||||
- **Role**: Clear role description
|
||||
- **Personality**: Personality traits and communication style
|
||||
- **Memory**: What the agent needs to remember and learn
|
||||
- **Experience**: Domain expertise and perspective
|
||||
|
||||
### 🎯 Core Mission
|
||||
- Core Responsibility 1 (with clear deliverables)
|
||||
- Core Responsibility 2 (with clear deliverables)
|
||||
- Core Responsibility 3 (with clear deliverables)
|
||||
- **Default Requirement**: Always follow best practices
|
||||
|
||||
### 🚨 Critical Rules
|
||||
Domain-specific rules and constraints that define how the agent operates.
|
||||
|
||||
### 📋 Technical Deliverables
|
||||
Concrete outputs the agent produces:
|
||||
- Code examples
|
||||
- Templates
|
||||
- Frameworks
|
||||
- Documentation
|
||||
|
||||
### 🔄 Workflow
|
||||
Step-by-step process the agent follows:
|
||||
1. Phase 1: Exploration & Research
|
||||
2. Phase 2: Planning & Strategy
|
||||
3. Phase 3: Execution & Implementation
|
||||
4. Phase 4: Review & Optimization
|
||||
|
||||
### 💭 Communication Style
|
||||
- How the agent communicates
|
||||
- Example phrases and expression patterns
|
||||
- Tone and style
|
||||
|
||||
### 🔄 Learning & Memory
|
||||
What the agent continuously learns from:
|
||||
- Success patterns
|
||||
- Failure cases
|
||||
- User feedback
|
||||
- Domain evolution
|
||||
|
||||
### 🎯 Success Metrics
|
||||
Quantifiable outcomes:
|
||||
- Quantitative metrics (with specific values)
|
||||
- Qualitative metrics
|
||||
- Performance benchmarks
|
||||
|
||||
### 🚀 Advanced Capabilities
|
||||
Advanced techniques and methods the agent masters.
|
||||
|
||||
## Connections
|
||||
- Implements [[Agent-Design-Principles]] — structural template for the five design principles
|
||||
- Used in [[Multi-Agent-Team]] — standardized agent creation
|
||||
|
||||
38
wiki/concepts/AgentIntegration.md
Normal file
38
wiki/concepts/AgentIntegration.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: "Agent Integration"
|
||||
type: concept
|
||||
tags: []
|
||||
sources: [qwen-readme]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Overview
|
||||
Agent Integration（Agent 集成适配）是将统一的 Markdown Agent 规范转换为各 AI 编码工具原生格式的适配层技术。The Agency 通过 `convert.sh` 和 `install.sh` 两层脚本实现这一目标。
|
||||
|
||||
## Definition
|
||||
Agent Integration = 统一的 Agent 行为规范（`.md`） + 工具特定的转换器（`convert.sh`） + 标准化的安装机制（`install.sh`）
|
||||
|
||||
## Key Properties
|
||||
- **单向转换**：从源 `.md` 到目标格式，不做反向同步
|
||||
- **工具原生**：转换后的格式是该工具推荐/唯一的配置方式
|
||||
- **作用域分层**：Home-Scoped（全用户级）vs Project-Scoped（项目级）
|
||||
- **注册机制差异**：部分工具依赖自动发现（如 Claude Code），部分需要显式启动参数（如 Kimi `--agent-file`）
|
||||
|
||||
## Integration Patterns
|
||||
| 工具 | 格式 | 作用域 | 注册机制 |
|
||||
|------|------|--------|---------|
|
||||
| Claude Code | `.md` | Home | 自动发现 |
|
||||
| GitHub Copilot | `.md` | Home | 自动发现 |
|
||||
| Antigravity | `SKILL.md` | Home | 工具内置 |
|
||||
| Gemini CLI | 扩展包 + Skill | Home | 自动加载 |
|
||||
| OpenCode | `.md` | Project | 自动发现 |
|
||||
| OpenClaw | `SOUL.md+AGENTS.md+IDENTITY.md` | Home | Gateway |
|
||||
| Cursor | `.mdc` | Project | 自动发现 |
|
||||
| Aider | `CONVENTIONS.md` | Project | 自动发现 |
|
||||
| Windsurf | `.windsurfrules` | Project | 自动发现 |
|
||||
| Kimi Code | YAML | Home | 显式启动参数 |
|
||||
| Qwen Code | `.md` SubAgent | Project | 自动发现 |
|
||||
|
||||
## Sources
|
||||
- [[OpenCode Integration]]（`Agent/agency-agents/integrations/README.md`）
|
||||
- [[OpenClaw Integration]]（`Agent/agency-agents/integrations/openclaw/README.md`）
|
||||
33
wiki/concepts/AgentScopes.md
Normal file
33
wiki/concepts/AgentScopes.md
Normal file
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: "Agent Scopes"
|
||||
type: concept
|
||||
tags: []
|
||||
last_updated: 2026-04-29
|
||||
---
|
||||
|
||||
## Overview
|
||||
Agent Scopes（Agent 作用域）指 AI 编码 Agent 的生效范围，决定了 Agent 配置是全局共享还是项目专用。这是 The Agency 集成架构中的重要维度。
|
||||
|
||||
## Home-Scoped Agent（全用户级 Agent）
|
||||
- 安装位置：用户家目录（如 `~/.claude/agents/`、`~/.gemini/`）
|
||||
- 生效范围：该用户所有项目均可用
|
||||
- 安装方式：`./scripts/install.sh --tool <tool>`
|
||||
- 代表工具：Claude Code、GitHub Copilot、Antigravity、Gemini CLI、OpenClaw、Kimi Code
|
||||
|
||||
## Project-Scoped Agent（项目级 Agent）
|
||||
- 安装位置：项目根目录（如 `./.opencode/agents/`、`./.windsurfrules`）
|
||||
- 生效范围：仅当前项目可用
|
||||
- 安装方式：从项目根目录运行 `./scripts/install.sh --tool <tool>`
|
||||
- 代表工具：OpenCode、Cursor、Aider、Windsurf、Qwen Code
|
||||
|
||||
## Key Differences
|
||||
| 维度 | Home-Scoped | Project-Scoped |
|
||||
|------|-------------|----------------|
|
||||
| 安装路径 | `~/.tool/` | `./.tool/` |
|
||||
| 多项目复用 | ✅ | ❌ |
|
||||
| 项目定制化 | ❌ | ✅ |
|
||||
| 权限控制 | 用户级 | 仓库级（可提交 git） |
|
||||
| 冲突风险 | 高（同名覆盖） | 低（项目隔离） |
|
||||
|
||||
## Sources
|
||||
- [[OpenCode Integration]]（`Agent/agency-agents/integrations/README.md`）
|
||||
24
wiki/concepts/AgentWorkspace.md
Normal file
24
wiki/concepts/AgentWorkspace.md
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: "Agent Workspace"
|
||||
type: concept
|
||||
tags: []
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Overview
|
||||
Agent Workspace（Agent 工作区）是 AI Agent 的定义容器单元，包含 Agent 的全部行为规范、身份和配置信息。
|
||||
|
||||
## Definition
|
||||
Agent Workspace = 行为规范（AGENTS.md/SOUL.md）+ 身份定义（IDENTITY.md）+ 其他配置文件
|
||||
|
||||
## Key Properties
|
||||
- **多文件结构**：OpenClaw Workspace 包含 `SOUL.md`（核心理念）、`AGENTS.md`（行为规范）、`IDENTITY.md`（身份定义）三文件
|
||||
- **安装即注册**：Workspace 复制到目标路径即完成 Agent 注册，无需额外配置
|
||||
- **工具特定性**：不同工具对 Workspace 格式要求不同（OpenClaw 三文件 vs OpenCode 单文件）
|
||||
|
||||
## Relationships
|
||||
- [[AgentIntegration]] ← uses ← [[AgentWorkspace]]（Workspace 是集成的最小单元）
|
||||
- [[OpenClaw]] ← manages ← [[AgentWorkspace]]
|
||||
|
||||
## Sources
|
||||
- [[OpenClaw Integration]]（`Agent/agency-agents/integrations/openclaw/README.md`）
|
||||
37
wiki/concepts/AirGappedSLMFixGeneration.md
Normal file
37
wiki/concepts/AirGappedSLMFixGeneration.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: "Air-Gapped SLM Fix Generation"
|
||||
type: concept
|
||||
tags: []
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
在完全离线（气隙）的环境中，通过本地 Small Language Models（SLM，如 Ollama 运行的 Phi-3/Llama-3/Mistral）生成确定性修复逻辑（Python lambda）的方法论。
|
||||
|
||||
## Core Principle
|
||||
|
||||
**AI generates logic — never touches data directly.**
|
||||
|
||||
SLM 输出的是一个转换函数（lambda），由系统执行，而非 AI 直接修改数据。这样保证了可审计、可回滚、可解释的数据变更。
|
||||
|
||||
## Workflow
|
||||
|
||||
1. SLM 接收聚类样本 + 列名
|
||||
2. SLM 输出严格格式化的 JSON（含 transformation、confidence_score、reasoning、pattern_type）
|
||||
3. Lambda Safety Gate 验证（必须以 `lambda` 开头，不含 `import/exec/eval/os/subprocess`）
|
||||
4. 验证通过后向量化执行于整个聚类
|
||||
5. 低于 0.75 置信度的自动进入人工隔离队列
|
||||
|
||||
## Safety Guarantees
|
||||
|
||||
- **Zero PII Egress**: 所有处理完全本地，无网络出口
|
||||
- **Deterministic Output**: SLM 输出确定性 lambda，不做创意性文本生成
|
||||
- **Safety Gate**: 任何包含危险关键词的 lambda 立即被拒绝并路由至隔离区
|
||||
- **Audit Trail**: 每条数据变更记录完整上下文
|
||||
|
||||
## Related
|
||||
|
||||
- [[Semantic Anomaly Compression]]
|
||||
- [[Lambda Safety Gate]]
|
||||
- [[AI Generates Logic Not Data]]
|
||||
@@ -1,40 +1,44 @@
|
||||
---
|
||||
title: "Annales School"
|
||||
type: concept
|
||||
tags: ["historiography", "french-history", "material-culture", "longue-duree"]
|
||||
sources: ["academic-historian"]
|
||||
last_updated: 2026-04-25
|
||||
---
|
||||
|
||||
## Definition
|
||||
法国史学流派，以《年鉴》（*Annales d'histoire économique et sociale*，1929年创刊）为核心阵地，由马克·布洛赫（Marc Bloch）和吕西安·费弗尔（Lucien Febvre）共同创立。主张历史研究应突破传统政治军事史的局限，关注普通人的日常生活、物质条件和长期社会结构。
|
||||
|
||||
## Core Principles
|
||||
- **物质条件优先**：在讨论政治/军事/思想之前，必须先理解经济基础、农业、贸易和技术
|
||||
- **长时段视角（Longue Durée）**：历史变化发生在几十年乃至几个世纪的时间尺度上，聚焦于塑造事件发生的深层结构
|
||||
- **日常生活史（*Histoire du quotidien*）**：关注饮食、服饰、建筑、信仰、恐惧——Annales 学派不只写国王和战争
|
||||
- **跨学科方法**：整合地理学、经济学、社会学、人类学、人口学的方法论
|
||||
- **问题导向史学**：以问题而非编年驱动历史研究
|
||||
|
||||
## Key Figures
|
||||
- **马克·布洛赫**（Marc Bloch，1886-1944）：年鉴学派创始人之一，《封建社会》作者，二战期间参加抵抗运动后被枪决
|
||||
- **吕西安·费弗尔**（Lucien Febvre，1878-1956）：年鉴学派创始人之一，专注于16世纪精神状态史
|
||||
- **费尔南·布罗代尔**（Fernand Braudel，1902-1985）：年鉴学派第二代领袖，《菲利普二世时代的地中海和地中海世界》——长时段理论的奠基之作，将历史分为三个时间层次：地理时间（长时段）、社会时间（中时段）、事件时间（短时段）
|
||||
- **埃马纽埃尔·勒华拉杜里**（Emmanuel Le Roy Ladurie，*Montaillou* 作者）：微观史的代表人物
|
||||
|
||||
## Relationship to Historiography
|
||||
- **反对**：兰克学派（Rankean）聚焦政治史和伟大人物的传统史学；辉格史观（Whig History）以现代标准评判历史
|
||||
- **影响**：新文化史、微观史、历史社会学、后殖民史学均受其影响
|
||||
- **对话/张力**：年鉴学派有时因过度关注结构而被批评忽视个体能动性（agency），微观史（Microhistory）部分是对此的回应
|
||||
|
||||
## Connections
|
||||
- [[Geographic-Coherence]] ← 理论关联 ← [[Annales-School]]：两者都强调物质地理条件对人类历史的约束作用
|
||||
- [[academic-historian]] ← 方法论来源 ← [[Annales-School]]：Historian Agent 优先使用年鉴学派方法
|
||||
- [[Longue-Duree]] ← 核心概念 ← [[Annales-School]]：长时段分析是年鉴学派最重要的方法论贡献
|
||||
|
||||
## Aliases
|
||||
- 年鉴学派
|
||||
- Annales
|
||||
- Annales d'histoire économique et sociale
|
||||
- Annales School of historiography
|
||||
- French historical school
|
||||
---
|
||||
title: "Annales School"
|
||||
type: concept
|
||||
tags: ["historiography", "french-history", "material-culture", "longue-duree"]
|
||||
sources: ["academic-historian"]
|
||||
last_updated: 2026-04-25
|
||||
---
|
||||
|
||||
## Definition
|
||||
法国史学流派，以《年鉴》（*Annales d'histoire économique et sociale*，1929年创刊）为核心阵地，由马克·布洛赫（Marc Bloch）和吕西安·费弗尔（Lucien Febvre）共同创立。主张历史研究应突破传统政治军事史的局限，关注普通人的日常生活、物质条件和长期社会结构。
|
||||
|
||||
## Core Principles
|
||||
- **物质条件优先**：在讨论政治/军事/思想之前，必须先理解经济基础、农业、贸易和技术
|
||||
- **长时段视角（Longue Durée）**：历史变化发生在几十年乃至几个世纪的时间尺度上，聚焦于塑造事件发生的深层结构
|
||||
- **日常生活史（*Histoire du quotidien*）**：关注饮食、服饰、建筑、信仰、恐惧——Annales 学派不只写国王和战争
|
||||
- **跨学科方法**：整合地理学、经济学、社会学、人类学、人口学的方法论
|
||||
- **问题导向史学**：以问题而非编年驱动历史研究
|
||||
|
||||
## Key Figures
|
||||
- **马克·布洛赫**（Marc Bloch，1886-1944）：年鉴学派创始人之一，《封建社会》作者，二战期间参加抵抗运动后被枪决
|
||||
- **吕西安·费弗尔**（Lucien Febvre，1878-1956）：年鉴学派创始人之一，专注于16世纪精神状态史
|
||||
- **费尔南·布罗代尔**（Fernand Braudel，1902-1985）：年鉴学派第二代领袖，《菲利普二世时代的地中海和地中海世界》——长时段理论的奠基之作，将历史分为三个时间层次：地理时间（长时段）、社会时间（中时段）、事件时间（短时段）
|
||||
- **埃马纽埃尔·勒华拉杜里**（Emmanuel Le Roy Ladurie，*Montaillou* 作者）：微观史的代表人物
|
||||
|
||||
## Relationship to Historiography
|
||||
- **反对**：兰克学派（Rankean）聚焦政治史和伟大人物的传统史学；辉格史观（Whig History）以现代标准评判历史
|
||||
- **影响**：新文化史、微观史、历史社会学、后殖民史学均受其影响
|
||||
- **对话/张力**：年鉴学派有时因过度关注结构而被批评忽视个体能动性（agency），微观史（Microhistory）部分是对此的回应
|
||||
|
||||
- [[Microhistory]] ← 方法论回应 ← [[Annales-School]]：微观史是对年鉴学派过度结构决定论批评的回应之一
|
||||
- [[Material-Culture]] ← 核心关注 ← [[Annales-School]]：物质文化是年鉴学派历史分析的第一层
|
||||
|
||||
## Connections
|
||||
- [[Geographic-Coherence]] ← 理论关联 ← [[Annales-School]]：两者都强调物质地理条件对人类历史的约束作用
|
||||
- [[academic-historian]] ← 方法论来源 ← [[Annales-School]]：Historian Agent 优先使用年鉴学派方法
|
||||
- [[Longue-Duree]] ← 核心概念 ← [[Annales-School]]：长时段分析是年鉴学派最重要的方法论贡献
|
||||
- [[Microhistory]] ← 方法论互补 ← [[Annales-School]]：微观史是对年鉴学派的结构决定论倾向的回应
|
||||
|
||||
## Aliases
|
||||
- 年鉴学派
|
||||
- Annales
|
||||
- Annales d'histoire économique et sociale
|
||||
- Annales School of historiography
|
||||
- French historical school
|
||||
|
||||
@@ -1,43 +1,39 @@
|
||||
---
|
||||
title: "Answer Engine Optimization (AEO)"
|
||||
title: "Answer Engine Optimization"
|
||||
type: concept
|
||||
tags: ["AI", "SEO", "marketing", "visibility"]
|
||||
last_updated: 2026-04-26
|
||||
tags: ["SEO", "AI", "marketing", "AEO"]
|
||||
sources: ["marketing-ai-citation-strategist"]
|
||||
last_updated: 2026-04-30
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Answer Engine Optimization (AEO) 是针对 AI 问答引擎的优化策略，旨在使品牌内容被 AI 助手（ChatGPT、Claude、Gemini、Perplexity 等）在生成答案时引用。与传统 SEO 不同，AEO 的目标不是让页面在搜索结果中排名靠前，而是让内容成为 AI 合成的"可信来源"。
|
||||
Answer Engine Optimization（AEO，答案引擎优化）：一种专注于让内容在 AI 推荐引擎（如 ChatGPT、Claude、Gemini、Perplexity）中被直接引用推荐的营销技术。与传统 SEO 不同，AEO 优化的不是页面排名，而是内容被 AI 合成答案选为来源的可能性。
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **答案优先**：内容应直接回答用户问题，而非围绕关键词优化
|
||||
2. **结构化权威**：使用 FAQ、步骤指南、对比表格等 AI 友好格式
|
||||
3. **实体清晰**：明确的品牌、产品、概念实体标注
|
||||
4. **来源归属**：让 AI 能准确识别内容归属和可信度
|
||||
1. **AI 引用 ≠ SEO 排名**：SEO 信号（关键词密度、反向链接、页面速度）与 AEO 信号（实体清晰度、结构化权威、FAQ 对齐、Schema 标记）完全不同
|
||||
2. **引用是概率性的**：AI 响应具有非确定性，只能"提升引用概率"而非"保证被引用"
|
||||
3. **多平台差异化**：每个 AI 引擎有不同内容偏好和引用行为，必须针对平台定制
|
||||
|
||||
## AEO vs SEO
|
||||
## Key Signals
|
||||
|
||||
| 维度 | 传统 SEO | AEO |
|
||||
|------|---------|-----|
|
||||
| 目标 | 页面排名 | 被引用为来源 |
|
||||
| 优化对象 | 搜索引擎爬虫 | AI 模型推理 |
|
||||
| 核心信号 | 外链、关键词密度 | 实体清晰度、Schema markup、FAQ 对齐 |
|
||||
| 衡量指标 | 排名、点击率 | Citation Rate、Share of Voice |
|
||||
|
||||
## Key Tactics
|
||||
|
||||
- **FAQ Schema**：添加 FAQPage/FAQQuestion schema markup
|
||||
- **How-To Content**：结构化步骤指南，满足"How to"类查询
|
||||
- **Comparison Pages**：独立的品牌/产品对比页，满足"X vs Y"类查询
|
||||
- **Direct Answers**：在内容开头直接给出答案，而非铺垫
|
||||
| 信号类型 | 说明 | 适用平台 |
|
||||
|---------|------|---------|
|
||||
| Entity Clarity | 品牌/产品在知识图谱中清晰可识别 | 所有平台 |
|
||||
| Structured Authority | FAQ、对比表、how-to指南等结构化内容 | ChatGPT/Gemini |
|
||||
| FAQ Alignment | Q&A 内容匹配用户实际输入 AI 的查询模式 | ChatGPT |
|
||||
| Schema Markup | Organization/Product/FAQ 结构化数据 | Gemini/Perplexity |
|
||||
| Source Diversity | 多样化的权威来源引用 | Perplexity |
|
||||
| Recency | 时效性内容 | Perplexity |
|
||||
|
||||
## Related Concepts
|
||||
|
||||
- [[Generative Engine Optimization (GEO)]]：更广泛的生成式 AI 引擎可见性优化
|
||||
- [[Citation Rate]]：衡量 AEO 效果的量化指标
|
||||
- [[Entity Optimization]]：实体信号强化是 AEO 的核心技术
|
||||
- [[Generative Engine Optimization]]（GEO）— AEO 的扩展，涵盖更广泛的 AI 生成内容可见性
|
||||
- [[Schema Markup]] — AEO 的关键技术手段之一
|
||||
- [[Citation Audit Scorecard]] — AEO 效果的可量化评估工具
|
||||
|
||||
## Sources
|
||||
## Relationships
|
||||
|
||||
- [[AI Citation Strategist]]
|
||||
- 互补于 → [[marketing-seo-specialist]]
|
||||
- 扩展为 → [[marketing-ai-citation-strategist]]
|
||||
|
||||
@@ -1,39 +1,41 @@
|
||||
---
|
||||
title: "Architectural Empathy"
|
||||
type: concept
|
||||
tags: [ux-design, cultural-intelligence, design-philosophy]
|
||||
sources: [specialized-cultural-intelligence-strategist]
|
||||
last_updated: 2026-04-25
|
||||
---
|
||||
|
||||
## Definition
|
||||
通过结构性解决方案而非表演性行为来实现包容性的设计哲学——在系统架构层面消除排斥根源，而非在产品表面添加"看起来包容"的元素。Architectural Empathy Engine 是 [[Cultural-Intelligence-Strategist]] 的角色定位，强调同理心必须融入产品的骨架，而非仅装饰于表面。
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Structural > Cosmetic
|
||||
- ❌ 在首页添加一张多元人群图
|
||||
- ✅ 重新设计表单字段以接受全球命名结构
|
||||
|
||||
### 2. Precondition, Not Afterthought
|
||||
- ❌ 产品上线后再考虑国际化
|
||||
- ✅ 国际化是架构设计的前提条件（Global-First Architecture）
|
||||
|
||||
### 3. "Who is left out?" as First Question
|
||||
每个工作流审查的第一个问题必须是："如果用户是神经多样性者、视障者、非西方文化背景者、或使用不同历法，这个设计还能工作吗？"
|
||||
|
||||
### 4. Absolute Cultural Humility
|
||||
永远不声称当前知识是完整的。在为任何群体生成内容前，必须自主研究该群体的当前、尊重、赋权的表征标准。
|
||||
|
||||
## Relationship to Other Concepts
|
||||
- [[Invisible-Exclusion]]：Architectural Empathy 的诊断对象
|
||||
- [[Global-First-Architecture]]：Architectural Empathy 的实施方法
|
||||
- [[Cultural-Intelligence]]：Architectural Empathy 的知识基础
|
||||
|
||||
## Contrast: Performative vs. Structural Empathy
|
||||
| 维度 | 表演性同理心 | 结构性同理心 |
|
||||
|------|------------|------------|
|
||||
| 位置 | 表面层 | 架构层 |
|
||||
| 效果 | 短期感知改善 | 长期用户摩擦消除 |
|
||||
| 检测方式 | 多元图片存在 | APAC 用户转化率提升 |
|
||||
| 维护 | 每次更新需重新添加 | 架构内建，持续有效 |
|
||||
---
|
||||
title: "Architectural Empathy"
|
||||
type: concept
|
||||
tags: [ux-design, cultural-intelligence, design-philosophy]
|
||||
sources: [specialized-cultural-intelligence-strategist]
|
||||
last_updated: 2026-05-29
|
||||
---
|
||||
|
||||
## Definition
|
||||
通过结构性解决方案而非表演性行为来实现包容性的设计哲学——在系统架构层面消除排斥根源，而非在产品表面添加"看起来包容"的元素。Architectural Empathy Engine 是 [[Cultural-Intelligence-Strategist]] 的角色定位，强调同理心必须融入产品的骨架，而非仅装饰于表面。
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Structural > Cosmetic
|
||||
- ❌ 在首页添加一张多元人群图
|
||||
- ✅ 重新设计表单字段以接受全球命名结构
|
||||
|
||||
### 2. Precondition, Not Afterthought
|
||||
- ❌ 产品上线后再考虑国际化
|
||||
- ✅ 国际化是架构设计的前提条件（Global-First Architecture）
|
||||
|
||||
### 3. "Who is left out?" as First Question
|
||||
每个工作流审查的第一个问题必须是："如果用户是神经多样性者、视障者、非西方文化背景者、或使用不同历法，这个设计还能工作吗？"
|
||||
|
||||
### 4. Absolute Cultural Humility
|
||||
永远不声称当前知识是完整的。在为任何群体生成内容前，必须自主研究该群体的当前、尊重、赋权的表征标准。
|
||||
|
||||
## Relationship to Other Concepts
|
||||
- [[Invisible-Exclusion]]：Architectural Empathy 的诊断对象
|
||||
- [[Global-First-Architecture]]：Architectural Empathy 的实施方法
|
||||
- [[Cultural-Intelligence]]：Architectural Empathy 的知识基础
|
||||
|
||||
## Aliases
|
||||
- Structural Empathy（结构性同理心）
|
||||
- Architectural Empathy
|
||||
| 维度 | 表演性同理心 | 结构性同理心 |
|
||||
|------|------------|------------|
|
||||
| 位置 | 表面层 | 架构层 |
|
||||
| 效果 | 短期感知改善 | 长期用户摩擦消除 |
|
||||
| 检测方式 | 多元图片存在 | APAC 用户转化率提升 |
|
||||
| 维护 | 每次更新需重新添加 | 架构内建，持续有效 |
|
||||
|
||||
50
wiki/concepts/ArchitectureDecisionRecord.md
Normal file
50
wiki/concepts/ArchitectureDecisionRecord.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: "Architecture Decision Record"
|
||||
type: concept
|
||||
tags: []
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Definition
|
||||
Architecture Decision Record（架构决策记录）是一种轻量级文档，用于捕获架构决策的上下文、选项和理由。ADR 记录的是"为什么这样做"，而不仅仅是"做了什么"。
|
||||
|
||||
## ADR Format
|
||||
|
||||
```markdown
|
||||
# ADR-001: [Decision Title]
|
||||
|
||||
## Status
|
||||
Proposed | Accepted | Deprecated | Superseded by ADR-XXX
|
||||
|
||||
## Context
|
||||
What is the issue that we're seeing that is motivating this decision?
|
||||
|
||||
## Decision
|
||||
What is the change that we're proposing and/or doing?
|
||||
|
||||
## Consequences
|
||||
What becomes easier or harder because of this change?
|
||||
```
|
||||
|
||||
## Key Elements
|
||||
- **Status**：Proposed（提议中）/ Accepted（已接受）/ Deprecated（已废弃）/ Superseded（被替代）
|
||||
- **Context**：驱动决策的问题或背景
|
||||
- **Decision**：具体的决策内容
|
||||
- **Consequences**：决策的后果——什么变得更容易，什么变得更难
|
||||
|
||||
## Core Principles
|
||||
- **记录 WHY，而非 WHAT**：代码已经说明了"做了什么"，ADR 应该说明"为什么这样做"
|
||||
- **可追溯性**：随着系统演进，ADR 提供了决策的历史脉络
|
||||
- **知识共享**：新成员可以通过 ADR 理解架构决策的背景
|
||||
|
||||
## Related Concepts
|
||||
- [[SoftwareArchitect]]：ADR 是 Software Architect Agent 的核心工具之一
|
||||
- [[DomainDrivenDesign]]：ADR 常用于记录领域模型的边界决策
|
||||
|
||||
## Sources
|
||||
- [[engineering-software-architect]]
|
||||
|
||||
## Aliases
|
||||
- ADR
|
||||
- Architecture Decision Record
|
||||
- 架构决策记录
|
||||
38
wiki/concepts/Atomic-Note.md
Normal file
38
wiki/concepts/Atomic-Note.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: "Atomic Note"
|
||||
type: concept
|
||||
tags: [knowledge-management, zettelkasten, note-taking]
|
||||
sources: [zk-steward]
|
||||
last_updated: 2026-05-30
|
||||
---
|
||||
|
||||
## Overview
|
||||
Atomic Note（原子笔记）是 Zettelkasten 系统的基本工作单位——最小的、自包含的知识单元。它必须满足 [[Luhmann-四原则]]中的原子性要求：可以独立理解，不依赖上下文而存在。
|
||||
|
||||
## Definition
|
||||
一个原子笔记 = 一个想法 + 一个唯一标识 + 至少两条指向其他笔记的链接
|
||||
|
||||
## Properties
|
||||
- **Self-contained**：即使没有上下文，读者也能理解笔记的内容
|
||||
- **Single idea**：一个笔记只讨论一个核心主题（one idea per note）
|
||||
- **Linked**：至少拥有 ≥2 条指向其他笔记/概念/实体的有意义的 wikilinks
|
||||
- **Non-categorical**：不依赖文件夹层级分类，而是通过网络位置定义自己
|
||||
|
||||
## 与 Related Concepts 的关系
|
||||
- [[Zettelkasten]] ← Atomic Note 是 Zettelkasten 的基本工作单位
|
||||
- [[Luhmann-四原则]] ← 原子性（Atomicity）是 Luhmann 四原则之一，直接定义了 Atomic Note 的核心属性
|
||||
- [[Link-Proposer]] ← 新笔记归档时，Link-Proposer 确保原子笔记拥有 ≥2 条链接
|
||||
- [[Domain-Thinking]] ← 领域专家切换生成的内容，最终需要转化为原子笔记嵌入知识网络
|
||||
|
||||
## 创建条件
|
||||
- 可独立理解（通过 Luhmann 原子性测试）
|
||||
- 包含 ≥2 条有意义的链接
|
||||
- 避免"零链接笔记"——零链接笔记违反 [[ZK-Steward-Agent]] 的核心规则
|
||||
|
||||
## Example（来自 ZK Steward Agent 文档中的结构笔记示例）
|
||||
```markdown
|
||||
## [Title] Structure Note
|
||||
> **Context**: When, why, and under what project this was created.
|
||||
> **Default reader**: Yourself in six months—this structure is self-contained.
|
||||
```
|
||||
结构笔记下挂载多个原子笔记，每个原子笔记对应一个可独立理解的概念或论断。
|
||||
33
wiki/concepts/AttachmentTheory.md
Normal file
33
wiki/concepts/AttachmentTheory.md
Normal file
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: "Attachment Theory"
|
||||
type: concept
|
||||
tags: []
|
||||
sources: [academic-psychologist]
|
||||
last_updated: 2026-04-25
|
||||
---
|
||||
|
||||
# Attachment Theory
|
||||
|
||||
## Definition
|
||||
Bowlby 依恋理论——认为早期与主要照顾者的关系模式会形成内部工作模型，影响个体一生中所有亲密关系的建立方式。
|
||||
|
||||
## Four Attachment Styles
|
||||
|
||||
| 风格 | 特征 | 关系中的行为模式 |
|
||||
|------|------|-----------------|
|
||||
| Secure（安全型） | 信任、情绪调节良好 | 能亲密也能独立 |
|
||||
| Anxious-Preoccupied（焦虑型） | 害怕被抛弃、过度依赖 | 粘人、情绪化索取 |
|
||||
| Dismissive-Avoidant（回避型） | 情感独立、贬低亲密 | 逃避亲密、压抑情感 |
|
||||
| Fearful-Avoidant（恐惧型） | 既渴望又害怕亲密 | 矛盾、忽冷忽热 |
|
||||
|
||||
## Key Concepts
|
||||
- **内部工作模型**（Internal Working Model）：对自我和他人的认知图式
|
||||
- **依恋唤起**（Attachment Activation）：压力情境触发依恋系统
|
||||
- **依恋回避**（Attachment Avoidance）：通过情感疏离应对亲密需求
|
||||
- **依恋焦虑**（Attachment Anxiety）：通过过度寻求确认应对被遗弃恐惧
|
||||
|
||||
## Application in Character Design
|
||||
Psychologist Agent 在评估角色时，要求标注依恋风格及其在**浪漫/家庭/友谊**三种关系类型中的不同表现，并识别特定触发情境。
|
||||
|
||||
## Connection to Wiki
|
||||
- Source: [[academic-psychologist]]
|
||||
51
wiki/concepts/AudienceStrategy.md
Normal file
51
wiki/concepts/AudienceStrategy.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: "Audience Strategy"
|
||||
type: concept
|
||||
tags: ["ppc", "audience", "targeting", "google-ads", "paid-media"]
|
||||
sources: ["paid-media-ppc-strategist"]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
受众策略（Audience Strategy）是付费媒体中通过分层构建、精准定向和动态优化，最大化广告触达正确用户群体的系统性方法。涵盖第一方数据激活（Customer Match）、相似受众（Similar Segments）、竞品受众（In-Market/Affinity）、自定义受众组合，以及排除策略的整体设计。
|
||||
|
||||
## Audience Layers
|
||||
|
||||
### Layer 1: First-Party Data（第一方数据）
|
||||
- **Customer Match**：自有客户邮箱/电话列表，直接匹配 Google 用户
|
||||
- **CRM Audiences**：基于 CRM 数据构建的自定义受众
|
||||
- **Website Visitors**：GA4/GBoard 追踪的网站访问者（再营销）
|
||||
- **App Users**：移动应用用户受众
|
||||
|
||||
### Layer 2: Similar / Lookalike（相似受众）
|
||||
- **Similar Segments**：在 Customer Match 基础上自动扩展相似新用户
|
||||
- **Value-Based Similar**：按客户生命周期价值（CLV）分层的相似受众
|
||||
|
||||
### Layer 3: In-Market / Affinity（兴趣受众）
|
||||
- **In-Market Audiences**：主动研究/比较中的潜在购买者（高转化潜力）
|
||||
- **Affinity Audiences**：长期兴趣/生活方式相关用户（品牌建设场景）
|
||||
- **Life Events**：人生重大事件（搬家/结婚/大学等）
|
||||
|
||||
### Layer 4: Demographic（人口统计）
|
||||
- **Age / Gender**：基础人口属性
|
||||
- **Household Income**：高收入人群定向（Premium 产品）
|
||||
- **Parental Status**：家长定向
|
||||
|
||||
## Targeting vs Observation Mode
|
||||
|
||||
| 模式 | 效果 |
|
||||
|------|------|
|
||||
| **Targeting** | 竞价时仅考虑定向人群，缩小范围 |
|
||||
| **Observation** | 观察指定人群表现，但不限制竞价范围 |
|
||||
|
||||
## Audience Exclusion
|
||||
|
||||
- **排除已转化用户**：避免浪费在已有客户身上
|
||||
- **排除低质量受众**：表现差的历史受众列表
|
||||
- **排除员工**：避免内部测试流量污染数据
|
||||
|
||||
## Connections
|
||||
- [[CustomerMatch]]：第一方数据激活的核心工具
|
||||
- [[PerformanceMax]]：Audience Signals 是 PMax 的关键输入
|
||||
- [[TieredCampaignArchitecture]]：不同层级的广告系列适用不同的受众策略
|
||||
53
wiki/concepts/Audit-Readiness.md
Normal file
53
wiki/concepts/Audit-Readiness.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: "Audit Readiness"
|
||||
type: concept
|
||||
tags: [finance, accounting, compliance, audit]
|
||||
sources: [finance-bookkeeper-controller]
|
||||
last_updated: 2026-05-02
|
||||
---
|
||||
|
||||
## Definition
|
||||
审计就绪（Audit Readiness）是指企业日常维护的持续合规状态，确保在任何时间点审计师进场都能在规定时间内（通常24小时）提供任何财务余额的支持文件。
|
||||
|
||||
## Core Principle
|
||||
> "Audit readiness is a daily practice. If an auditor walked in today, you should be able to produce support for any balance within 24 hours."
|
||||
> — Dana, Bookkeeper & Controller Agent
|
||||
|
||||
## Key Practices
|
||||
|
||||
### Daily Habits
|
||||
- 所有交易当天有支持文件
|
||||
- Journal entries 附带完整描述和审批记录
|
||||
- 银行对账每月及时完成
|
||||
- 所有支持文件归档有序
|
||||
|
||||
### Supporting Documentation Requirements
|
||||
| Balance Type | Required Support |
|
||||
|---|---|
|
||||
| Cash | 银行对账单 + 调节表 |
|
||||
| AR | Aging 报告 + 支持明细 |
|
||||
| AP | 供应商对账单 + 发票 |
|
||||
| Inventory | 盘点记录 |
|
||||
| Fixed Assets | 资产明细表 + 折旧表 |
|
||||
| Accruals | 计算底稿 |
|
||||
|
||||
### Control Testing
|
||||
- 所有关键控制有文档记录
|
||||
- 控制执行有证据（日志、审批截图）
|
||||
- 例外情况有书面说明
|
||||
|
||||
## Core Principle
|
||||
> "The audit should be boring. If the auditors are surprised, the controls failed."
|
||||
> — Dana, Bookkeeper & Controller Agent
|
||||
|
||||
## Success Metrics
|
||||
- 审计调整 < 1% 总资产
|
||||
- 零重述
|
||||
- 所有审计请求 24 小时内响应
|
||||
- 审计周期缩短（目标：无聊的审计 = 成功的审计）
|
||||
|
||||
## Related Concepts
|
||||
- [[Internal Controls]]
|
||||
- [[Account Reconciliation]]
|
||||
- [[Month-End-Close-Process]]
|
||||
- [[Segregation-Of-Duties]]
|
||||
42
wiki/concepts/AutomatedBiddingStrategy.md
Normal file
42
wiki/concepts/AutomatedBiddingStrategy.md
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: "Automated Bidding Strategy"
|
||||
type: concept
|
||||
tags: ["ppc", "bidding", "automation", "google-ads", "paid-media"]
|
||||
sources: ["paid-media-ppc-strategist"]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
自动化竞价策略（Automated Bidding Strategy）是 Google Ads 等平台提供的基于机器学习的智能出价系统，通过算法自动调整每次竞价出价，以优化预设的绩效目标（转化量、转化价值、ROAS 等）。区别于手动 CPC 出价，自动化竞价利用受众信号、上下文信号和历史数据自动优化。
|
||||
|
||||
## Available Strategies
|
||||
|
||||
| 策略 | 目标 | 适用场景 |
|
||||
|------|------|---------|
|
||||
| **Maximize Conversions** | 最大化转化量 | 数据充足、追求规模 |
|
||||
| **Maximize Conversion Value** | 最大化转化价值 | 客单价差异大、多产品 |
|
||||
| **tCPA（Target CPA）** | 固定平均单次转化成本 | 稳定转化数据、追求效率 |
|
||||
| **tROAS（Target ROAS）** | 固定广告支出回报率 | 有明确 ROAS 目标 |
|
||||
| **Enhanced CPC（ECPC）** | 在手动 CPC 基础上提升转化 | 向自动竞价过渡阶段 |
|
||||
| **Maximize Clicks** | 最大化点击量 | 流量获取阶段 |
|
||||
|
||||
## Transition Framework
|
||||
|
||||
从手动向自动竞价迁移的推荐路径：
|
||||
|
||||
1. **数据积累期**（4-6周）：手动 CPC + ECPC，建立转化数据基础
|
||||
2. **轻度自动化**（2-4周）：切换至 Maximize Conversions，监控效果
|
||||
3. **目标竞价**（持续）：根据业务目标选择 tCPA 或 tROAS
|
||||
|
||||
## Key Requirements
|
||||
|
||||
- **转化数据充足**：策略效果与数据量直接相关
|
||||
- **Conversion Action 正确配置**：追踪须准确，否则算法基于错误信号优化
|
||||
- **预算充足**：日预算至少达到目标 CPA 的 5-10 倍，保证算法学习
|
||||
- **时间窗口合理**：建议 4 周学习期后再评估效果
|
||||
|
||||
## Connections
|
||||
- [[GoogleAds]]：Google Ads 是最主要的自动化竞价平台
|
||||
- [[PerformanceMax]]：内置 Smart Bidding，是 AI 驱动优化的典型场景
|
||||
- [[TieredCampaignArchitecture]]：不同层级的广告系列适用不同竞价策略
|
||||
39
wiki/concepts/Automation-Decision-Framework.md
Normal file
39
wiki/concepts/Automation-Decision-Framework.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: "Automation Decision Framework"
|
||||
type: concept
|
||||
tags: [automation, governance, decision, evaluation]
|
||||
sources: [automation-governance-architect]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
# Automation Decision Framework
|
||||
|
||||
四维自动化评估框架，Automation Governance Architect 对每个自动化请求强制执行的决策前置步骤。
|
||||
|
||||
## 四维评估
|
||||
|
||||
### 1. Time Savings Per Month（月度时间节省）
|
||||
- 节省是否可持续且有意义？
|
||||
- 流程频率是否足以覆盖自动化开销？
|
||||
|
||||
### 2. Data Criticality（数据关键性）
|
||||
- 是否涉及客户、财务、合同或调度记录？
|
||||
- 错误 / 延迟 / 重复 / 缺失数据的 Impact 是什么？
|
||||
|
||||
### 3. External Dependency Risk（外部依赖风险）
|
||||
- 链条中有多少外部 API/服务？
|
||||
- 它们是否稳定、有文档、可观测？
|
||||
|
||||
### 4. Scalability 1x to 100x（可扩展性）
|
||||
- 重试、去重、速率限制在高负载下是否仍然有效？
|
||||
- 异常处理在大规模下是否仍可管理？
|
||||
|
||||
## 与 Verdict System 的关系
|
||||
|
||||
四维评估结果直接决定 [[Automation-Verdict-System]] 五级裁定：
|
||||
- 四维均达标 → APPROVE
|
||||
- 部分维度满足但有限制 → APPROVE AS PILOT / PARTIAL AUTOMATION ONLY
|
||||
- 任一维度存在重大问题 → DEFER / REJECT
|
||||
|
||||
## Sources
|
||||
- [[automation-governance-architect]]
|
||||
41
wiki/concepts/Automation-Verdict-System.md
Normal file
41
wiki/concepts/Automation-Verdict-System.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: "Automation Verdict System"
|
||||
type: concept
|
||||
tags: [automation, governance, verdict, decision]
|
||||
sources: [automation-governance-architect]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
# Automation Verdict System
|
||||
|
||||
五级自动化裁定结果体系，基于 [[Automation-Decision-Framework]] 四维评估后输出。
|
||||
|
||||
## 五级裁定
|
||||
|
||||
| 裁定 | 条件 | 含义 |
|
||||
|------|------|------|
|
||||
| **APPROVE** | 强价值 + 可控风险 + 可维护架构 | 可直接进入生产实施 |
|
||||
| **APPROVE AS PILOT** | 价值存在但需小范围验证 | 限定范围试点，验证后再全面铺开 |
|
||||
| **PARTIAL AUTOMATION ONLY** | 自动化安全段有价值，人工检查点不可少 | 仅自动化低风险环节，关键决策保留人工 |
|
||||
| **DEFER** | 流程不成熟 / 价值不明 / 依赖不稳定 | 暂不推进，等待条件成熟 |
|
||||
| **REJECT** | 经济性弱或运营/合规风险不可接受 | 明确拒绝，不进入实施阶段 |
|
||||
|
||||
## 核心原则
|
||||
|
||||
- **一次只选一个裁定**：不存在模糊状态
|
||||
- **裁定须附带理由**：Verdict 须对应 Rationale（业务 Impact / 关键风险 / 裁定依据）
|
||||
- **裁定附带架构建议**：即使 APPROVE 也需推荐 Architecture（触发点 / 验证逻辑 / 日志 / 错误处理 / Fallback）
|
||||
|
||||
## Required Output Format（裁定输出格式）
|
||||
|
||||
每份裁定必须包含：
|
||||
1. Process Summary（流程摘要）
|
||||
2. Audit Evaluation（四维评估）
|
||||
3. Verdict（裁定）
|
||||
4. Rationale（理由）
|
||||
5. Recommended Architecture（推荐架构）
|
||||
6. Implementation Standard（实施标准）
|
||||
7. Preconditions and Risks（前置条件和风险）
|
||||
|
||||
## Sources
|
||||
- [[automation-governance-architect]]
|
||||
51
wiki/concepts/Autoscaling.md
Normal file
51
wiki/concepts/Autoscaling.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: "Autoscaling"
|
||||
type: concept
|
||||
tags: [sre, cloud, scalability, reliability, kubernetes]
|
||||
last_updated: 2026-04-20
|
||||
---
|
||||
|
||||
# Autoscaling
|
||||
|
||||
自动扩缩容（Autoscaling）是云原生系统中根据负载自动调整资源容量的机制，但它与真正的弹性（Elasticity）有本质区别。
|
||||
|
||||
## Definition
|
||||
Autoscaling 通过预定义的规则（如 CPU 使用率、请求队列长度等）自动增加或减少计算资源。它是一种**被动的、反应式的**机制。
|
||||
|
||||
## Key Limitation
|
||||
> "Autoscaling is reactive, not resilient. Without caps, metrics, or overrides, it can worsen failures." — David Iyanu Jonathan
|
||||
|
||||
没有以下保护机制时，Autoscaling 可能**加剧故障**：
|
||||
- **上限（caps）**：防止无限扩容
|
||||
- **指标（metrics）**：确保扩容基于可靠数据
|
||||
- **覆盖机制（overrides）**：允许人工干预
|
||||
|
||||
## Autoscaling vs. Elasticity
|
||||
|
||||
| Aspect | Autoscaling | [[Elasticity]] |
|
||||
|--------|-------------|----------------|
|
||||
| 性质 | 被动的、反应式的 | 主动的、前瞻性的 |
|
||||
| 触发 | 基于指标阈值 | 基于策略和规划 |
|
||||
| 保护机制 | 可能缺失 | 必须具备 |
|
||||
| 故障时行为 | 可能加剧故障 | 设计上防止故障扩大 |
|
||||
|
||||
## Anti-Patterns
|
||||
- **Autoscaling to Death**：系统在负载高峰时无限扩容，导致资源耗尽
|
||||
- **No Upper Limits**：缺少上限导致成本爆炸
|
||||
- **Metrics Blindness**：依赖单一指标，忽视系统整体健康状况
|
||||
|
||||
## Best Practices
|
||||
1. 设置合理的扩容上限和缩容下限
|
||||
2. 配置多维度指标（不仅仅是 CPU）
|
||||
3. 建立人工覆盖机制
|
||||
4. 在非生产环境测试扩容策略
|
||||
5. 监控 Autoscaling 本身的行为
|
||||
|
||||
## Related Concepts
|
||||
- [[Elasticity]]
|
||||
- [[Scalability]]
|
||||
- [[Cluster-Autoscaler]]
|
||||
- [[Cost-Optimization]]
|
||||
|
||||
## Source
|
||||
- SRE Weekly Issue #513 — [[sre-weekly-issue-513]]
|
||||
33
wiki/concepts/Background-Job-Scheduling.md
Normal file
33
wiki/concepts/Background-Job-Scheduling.md
Normal file
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: "Background-Job-Scheduling"
|
||||
type: concept
|
||||
tags: []
|
||||
sources: [expose-hermes-agent-as-an-openai-compatible-api-for-any-frontend]
|
||||
last_updated: 2026-05-02
|
||||
---
|
||||
|
||||
## Definition
|
||||
Background Job Scheduling 是通过远程 API 管理定时和后台 Agent 任务的能力，使客户端无需长期保持连接即可触发和监控长时间运行的任务。
|
||||
|
||||
## Implementation in Hermes Agent
|
||||
`/api/jobs` API 提供完整的 CRUD 接口：
|
||||
- **Create**：创建定时任务或后台任务
|
||||
- **Read**：查询任务状态和结果
|
||||
- **Update**：修改任务参数或取消任务
|
||||
- **Delete**：删除任务
|
||||
|
||||
## Key Features
|
||||
- **定时执行**：支持 cron 表达式或延迟执行
|
||||
- **状态追踪**：实时查询任务执行状态
|
||||
- **结果获取**：任务完成后可获取完整输出
|
||||
- **远程管理**：客户端无需保持连接
|
||||
|
||||
## Use Cases
|
||||
- 定时报告生成
|
||||
- 批量数据处理
|
||||
- 定时通知发送
|
||||
- 后台数据同步
|
||||
|
||||
## Related
|
||||
- [[OpenAI-Compatible-API]]
|
||||
- [[Multi-Profile-Isolation]]
|
||||
24
wiki/concepts/Bearer-Token-Authentication.md
Normal file
24
wiki/concepts/Bearer-Token-Authentication.md
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: "Bearer-Token-Authentication"
|
||||
type: concept
|
||||
tags: []
|
||||
sources: [expose-hermes-agent-as-an-openai-compatible-api-for-any-frontend]
|
||||
last_updated: 2026-05-02
|
||||
---
|
||||
|
||||
## Definition
|
||||
Bearer Token Authentication 是一种 HTTP 认证机制，通过 `Authorization: Bearer <token>` 请求头传递令牌来验证 API 请求的合法性。
|
||||
|
||||
## Usage in Hermes Agent
|
||||
Hermes Agent API Server 使用 Bearer Token 认证：
|
||||
- **环境变量**：`API_SERVER_KEY` 设置认证密钥
|
||||
- **请求格式**：`Authorization: Bearer <API_SERVER_KEY>`
|
||||
- **适用场景**：任何调用 API Server 的客户端
|
||||
|
||||
## Security Notes
|
||||
- 当 API Server 绑定到非 loopback 地址（如 `0.0.0.0`）时，必须配置 `API_SERVER_KEY`
|
||||
- 默认绑定 `127.0.0.1:8642` 时仅本地访问可用，认证可选
|
||||
|
||||
## Related
|
||||
- [[OpenAI-Compatible-API]]
|
||||
- [[Multi-Profile-Isolation]]
|
||||
37
wiki/concepts/Behavioral-Analytics.md
Normal file
37
wiki/concepts/Behavioral-Analytics.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: "Behavioral Analytics"
|
||||
type: concept
|
||||
tags: [ux, behavioral-analytics, data-analysis, user-behavior, analytics]
|
||||
sources: [design-ux-researcher.md]
|
||||
last_updated: 2026-04-24
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Behavioral Analytics（行为分析）是一种通过收集、分析和解读用户在数字产品中的行为数据来识别使用模式、发现问题和优化机会的定量研究方法。是 UX Researcher Agent 在数字产品研究中的重要工具。
|
||||
|
||||
## Key Techniques
|
||||
|
||||
| 技术 | 说明 |
|
||||
|------|------|
|
||||
| Event Tracking | 追踪用户关键行为事件（点击/导航/停留） |
|
||||
| Funnel Analysis | 分析用户转化漏斗，识别流失点 |
|
||||
| Cohort Analysis | 按用户群组分析行为差异 |
|
||||
| Session Recording | 录制用户会话视频，还原真实行为 |
|
||||
|
||||
## Metrics
|
||||
|
||||
- **Activation Rate**：用户激活比例
|
||||
- **Engagement Rate**：用户参与度
|
||||
- **Retention Rate**：用户留存率
|
||||
- **Churn Rate**：用户流失率
|
||||
|
||||
## Relationship to Other Concepts
|
||||
|
||||
- [[Qualitative-Quantitative-Research]]：行为分析是定量研究方法的具体应用
|
||||
- [[User-Journey-Mapping]]：行为数据分析支撑用户旅程地图的构建
|
||||
- [[User-Research-Methodology]]：行为分析是混合研究方法的数据支撑层
|
||||
|
||||
## Source
|
||||
|
||||
- [[design-ux-researcher.md]] — UX Researcher Agent Personality
|
||||
33
wiki/concepts/BigFive.md
Normal file
33
wiki/concepts/BigFive.md
Normal file
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: "Big Five Personality Model"
|
||||
type: concept
|
||||
tags: []
|
||||
sources: [academic-psychologist]
|
||||
last_updated: 2026-04-25
|
||||
---
|
||||
|
||||
# Big Five Personality Model
|
||||
|
||||
## Aliases
|
||||
- Big Five
|
||||
- Five-Factor Model (FFM)
|
||||
- OCEAN Model
|
||||
|
||||
## Definition
|
||||
人格五因素模型——通过五个正交维度系统性评估和描述人格特质，是当前人格心理学中最具实证支持的结构框架。
|
||||
|
||||
## Five Factors
|
||||
|
||||
| 因素 | 高分特征 | 低分特征 |
|
||||
|------|----------|----------|
|
||||
| Openness（开放性） | 想象力、好奇心、艺术兴趣 | 务实、保守、按部就班 |
|
||||
| Conscientiousness（尽责性） | 自律、组织、成就导向 | 随性、冲动、拖延 |
|
||||
| Extraversion（外向性） | 社交、活力、寻求刺激 | 内向、安静、低社交需求 |
|
||||
| Agreeableness（宜人性） | 信任、合作、利他、谦逊 | 竞争、怀疑、自利 |
|
||||
| Neuroticism（神经质） | 焦虑、情绪不稳定、脆弱 | 情绪稳定、抗压、适应性强 |
|
||||
|
||||
## Application in Character Design
|
||||
Psychologist Agent 使用 Big Five 评估角色特质时，要求每个特质必须有对应的**行为表现**（behavioral manifestation），而非抽象标签。
|
||||
|
||||
## Connection to Wiki
|
||||
- Source: [[academic-psychologist]]
|
||||
110
wiki/concepts/BlamelessPostMortem.md
Normal file
110
wiki/concepts/BlamelessPostMortem.md
Normal file
@@ -0,0 +1,110 @@
|
||||
---
|
||||
title: "Blameless Post-Mortem"
|
||||
type: concept
|
||||
tags: [reliability, incident-management, culture]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Definition
|
||||
无责复盘（Blameless Post-Mortem）是一种以系统性视角分析事故的方法——归因于系统缺陷和流程缺口，而非个人错误。其核心原则：**"The system allowed this failure mode"**（系统允许了这种失败模式的存在），而非"X 人员导致了故障"。
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. 聚焦系统，不追责个人
|
||||
- **错误框架**："X 人员没有检查配置"
|
||||
- **正确框架**："系统没有强制执行配置验证流程"
|
||||
- 关键问题："系统缺少什么护栏/告警/测试，才让这个缺陷通过了？"
|
||||
|
||||
### 2. 5 Whys 根因分析
|
||||
通过连续追问找到系统性根本原因：
|
||||
1. 为什么服务宕机了？→ 配置文件错误
|
||||
2. 为什么配置文件错误？→ 变更审批未发现
|
||||
3. 为什么未发现？→ 没有自动化配置校验测试
|
||||
4. 为什么没有配置校验测试？→ 优先级未排入迭代
|
||||
5. 为什么未排入迭代？→ **系统根因**：没有将配置变更纳入质量门槛流程
|
||||
|
||||
### 3. 事实记录，时序重建
|
||||
- 按 UTC 时间重建完整事故时间线（从检测到恢复到后续跟进）
|
||||
- 记录实际采取的行动，而非"应该"采取的行动
|
||||
- 区分缓解措施（止血）和根因修复（治本）
|
||||
|
||||
### 4. 平衡"做得好的"和"做得差的"
|
||||
- **What Went Well**：有效的流程、工具和团队协作
|
||||
- **What Went Poorly**：拖慢检测或恢复的缺口
|
||||
|
||||
### 5. 行动项必须有跟踪
|
||||
- 每次复盘必须有具体行动项（Action Items）
|
||||
- 每个行动项：清晰的描述 + 负责人 + 优先级 + 截止日期
|
||||
- 无跟进行动项的复盘 = 只是会议
|
||||
|
||||
## Post-Mortem Document Structure
|
||||
|
||||
```markdown
|
||||
# Post-Mortem: [Incident Title]
|
||||
|
||||
**Date**: YYYY-MM-DD
|
||||
**Severity**: SEV[1-4]
|
||||
**Duration**: [start] – [end] ([total])
|
||||
**Author**: [name]
|
||||
**Status**: [Draft / Review / Final]
|
||||
|
||||
## Executive Summary
|
||||
[2-3句话：发生了什么、影响谁、如何解决]
|
||||
|
||||
## Impact
|
||||
- Users affected: [数量或百分比]
|
||||
- Revenue impact: [估算或 N/A]
|
||||
- SLO budget consumed: [月度错误预算消耗百分比]
|
||||
|
||||
## Timeline (UTC)
|
||||
| Time | Event |
|
||||
|-------|-------|
|
||||
| 14:02 | Monitoring alert fires: API error rate > 5% |
|
||||
| 14:05 | On-call engineer acknowledges page |
|
||||
| ... | ... |
|
||||
|
||||
## Root Cause Analysis
|
||||
### What happened
|
||||
[详细技术解释]
|
||||
|
||||
### Contributing Factors
|
||||
1. **Immediate**: [直接触发原因]
|
||||
2. **Underlying**: [为什么触发成为可能]
|
||||
3. **Systemic**: [组织/流程层面的缺口]
|
||||
|
||||
### 5 Whys
|
||||
1. Why...? → [answer]
|
||||
2. ...
|
||||
|
||||
## What Went Well
|
||||
-
|
||||
|
||||
## What Went Poorly
|
||||
-
|
||||
|
||||
## Action Items
|
||||
| ID | Action | Owner | Priority | Due | Status |
|
||||
|----|--------|-------|----------|-----|--------|
|
||||
| 1 | ... | @team | P1 | ... | Open |
|
||||
|
||||
## Lessons Learned
|
||||
[对未来架构和流程决策的启示]
|
||||
```
|
||||
|
||||
## Key Rules
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| 48 小时原则 | 事故解决后 48 小时内必须启动复盘（趁记忆鲜活） |
|
||||
| 心理安全 | 参与者必须感到安全，不能因发言而受到惩罚 |
|
||||
| 文档公开 | 复盘文档全公司可见，知识共享 |
|
||||
| 季度复盘 | 回顾过去季度的事故趋势，识别系统性风险 |
|
||||
|
||||
## Related Concepts
|
||||
- [[DORA-Metrics]] — 通过 MTTD、MTTR 等指标量化可靠性
|
||||
- [[DevOpsCulture]] — 无责文化是 DevOps 的核心支柱之一
|
||||
- [[Rollback-Rate]] — 回滚分析是复盘的重要输入
|
||||
- [[FiveWhys]] — 5问法是复盘根因分析的经典工具
|
||||
|
||||
## Sources
|
||||
- [[engineering-incident-response-commander]]
|
||||
45
wiki/concepts/Blended-Learning.md
Normal file
45
wiki/concepts/Blended-Learning.md
Normal file
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: "Blended Learning"
|
||||
type: concept
|
||||
tags: [learning-strategy, instructional-design]
|
||||
sources: [corporate-training-designer]
|
||||
last_updated: 2026-05-29
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Blended Learning（OMO，Online-Merge-Offline，线上线下融合学习）是将线上学习与线下面对面教学有机结合的学习模式，按照"知道→做到→持续"的认知规律分配学习场景，实现学习效果最大化。
|
||||
|
||||
## Three-Layer Model
|
||||
|
||||
### 线上 — "知道"（Knowing）
|
||||
- 知识传递：微课视频、文档阅读、在线测验
|
||||
- 特点：可随时随地学习，支持碎片化时间利用
|
||||
- 微课程规范：5-15分钟一门课，解决一个问题，结构清晰（痛点导入→知识传递→案例演示→要点总结）
|
||||
|
||||
### 线下 — "做到"（Doing）
|
||||
- 深度实践：小组讨论、角色扮演、沙盘模拟、动手练习
|
||||
- 特点：在安全环境中犯错误、即时反馈、行为强化
|
||||
- 场景类型：商业决策沙盘、项目管理沙盘、供应链沙盘等
|
||||
|
||||
### 学习社群 — "持续"（Sustaining）
|
||||
- 持续巩固：学习社区、答疑辅导、经验分享、行动学习
|
||||
- 特点：将一次性培训转化为持续学习行为
|
||||
|
||||
## Key Platforms（中国企业）
|
||||
- [[DingTalk-Learning]]（钉钉学习）：适合阿里巴巴生态企业，与钉钉 OA 深度集成
|
||||
- [[WeCom-Learning]]（企业微信学习）：适合微信生态企业，嵌入公众号和小程序
|
||||
- [[Feishu-Knowledge-Base]]（飞书知识库）：适合字节跳动生态和知识管理导向组织
|
||||
- [[UMU]]：混合学习领域领先者，支持 AI 练习搭档、视频作业、丰富互动功能
|
||||
- [[Yunxuetang]]（云学堂）：大中型企业一站式学习平台
|
||||
|
||||
## Instructional Design Principles
|
||||
- **场景匹配**：知识类内容适合线上，技能类内容必须线下实践
|
||||
- **认知负荷控制**：线上微课控制在15分钟以内；线下培训每90分钟安排互动或休息
|
||||
- **行为迁移设计**：每次线下练习必须设计行为迁移任务，确保学员回去能用
|
||||
|
||||
## Connections
|
||||
- [[Blended-Learning]] ← learning_strategy ← [[Corporate-Training-Designer]]（培训设计师的核心交付模式）
|
||||
- [[Flipped-Classroom]] ← practice_application ← [[Blended-Learning]]（翻转课堂是混合学习的一种实践形式）
|
||||
- [[Kolbs-Learning-Cycle]] ← theoretical_basis ← [[Blended-Learning]]（Kolb 体验学习圈为混合学习的场景分配提供理论依据）
|
||||
- [[Blended-Learning]] ← platform_infrastructure ← [[Blended-Learning-Platform]]（学习平台是混合学习的技术支撑）
|
||||
53
wiki/concepts/Bloom-Taxonomy.md
Normal file
53
wiki/concepts/Bloom-Taxonomy.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: "Bloom Taxonomy"
|
||||
type: concept
|
||||
tags: [cognitive-theory, learning-objectives]
|
||||
sources: [corporate-training-designer]
|
||||
last_updated: 2026-05-29
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Bloom 认知分类法（Blooms Taxonomy）由 Benjamin Bloom 等人于 1956 年提出，是一种按认知复杂度排序的学习目标分类体系，包含六个层级（记忆→理解→应用→分析→评价→创造），用于设计学习目标和评估标准。
|
||||
|
||||
## Six Levels
|
||||
|
||||
### Level 1 — Remember（记忆）
|
||||
- 识别、回忆事实性信息
|
||||
- 关键词：列出、定义、命名、辨认
|
||||
- 示例：列举企业培训的五种常见形式
|
||||
|
||||
### Level 2 — Understand（理解）
|
||||
- 解释信息的含义
|
||||
- 关键词：总结、解释、举例、分类
|
||||
- 示例：用自己的话解释 ADDIE 模型的五个阶段
|
||||
|
||||
### Level 3 — Apply（应用）
|
||||
- 将知识用于新情境
|
||||
- 关键词：执行、使用、演示、解决
|
||||
- 示例：在给定的业务场景中，选择合适的教学策略
|
||||
|
||||
### Level 4 — Analyze（分析）
|
||||
- 区分整体与部分，理解各部分之间的关系
|
||||
- 关键词：比较、对比、分解、辨别
|
||||
- 示例：分析某培训课程失败的原因，找出关键要素
|
||||
|
||||
### Level 5 — Evaluate（评价）
|
||||
- 基于标准做出判断
|
||||
- 关键词：评价、批判、选择、支持
|
||||
- 示例：评估两种教学设计方案的优劣
|
||||
|
||||
### Level 6 — Create（创造）
|
||||
- 将要素重组为新结构
|
||||
- 关键词：设计、构建、创造、制定
|
||||
- 示例：设计一套完整的新员工培训方案
|
||||
|
||||
## Applications in Training Design
|
||||
- **学习目标撰写**：使用 Bloom 动词明确每个学习目标的认知层级
|
||||
- **评估设计**：根据 Bloom 层级设计相应的评估方式（记忆→选择题；应用→案例分析；创造→方案设计）
|
||||
- **内容深度把控**：确保课程内容覆盖多个认知层级，而不仅是最低层级的"知识灌输"
|
||||
|
||||
## Connections
|
||||
- [[Bloom-Taxonomy]] ← learning_objective_framework ← [[ADDIE-Model]]（ADDIE 的设计阶段使用 Bloom 分类定义学习目标）
|
||||
- [[Bloom-Taxonomy]] ← cognitive_level ← [[Kirkpatrick-Model]]（Bloom 定义"学到什么层级"，Kirkpatrick 验证"是否真的学到了"）
|
||||
- [[Corporate-Training-Designer]] ← uses ← [[Bloom-Taxonomy]]（培训设计师必须掌握的核心教学设计工具）
|
||||
44
wiki/concepts/Brand-Foundation-Framework.md
Normal file
44
wiki/concepts/Brand-Foundation-Framework.md
Normal file
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: "Brand Foundation Framework"
|
||||
type: concept
|
||||
tags: [brand, strategy, framework]
|
||||
last_updated: 2026-05-15
|
||||
sources: [design-brand-guardian]
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
品牌基础框架是定义品牌存在的完整战略体系，包含 Purpose（存在意义）、Vision（愿景）、Mission（使命）、Values（价值观）和 Personality（个性）五个核心维度。该框架是所有品牌决策的基础，确保品牌在所有触点的一致性和差异化。
|
||||
|
||||
## Core Components
|
||||
|
||||
### Brand Purpose（存在意义）
|
||||
品牌超越盈利之外的存在意义——有意义的价值和影响创造。回答"为什么品牌存在"。
|
||||
|
||||
### Brand Vision（愿景）
|
||||
品牌追求的理想未来状态——品牌发展方向和成就。回答"品牌想去哪里"。
|
||||
|
||||
### Brand Mission（使命）
|
||||
品牌具体做什么、为谁做——价值交付和目标受众。回答"品牌做什么、为谁做"。
|
||||
|
||||
### Brand Values（价值观）
|
||||
指导所有品牌行为和决策的核心原则，例如：
|
||||
1. Primary Value：定义及行为表现
|
||||
2. Secondary Value：定义及行为表现
|
||||
3. Supporting Value：定义及行为表现
|
||||
|
||||
### Brand Personality（个性）
|
||||
定义品牌特征的人类特征，例如：
|
||||
- Trait 1：描述及表达方式
|
||||
- Trait 2：描述及表达方式
|
||||
- Trait 3：描述及表达方式
|
||||
|
||||
## Brand Promise
|
||||
对客户和利益相关者的承诺——他们可以永远期待什么。
|
||||
|
||||
## Connections
|
||||
|
||||
- [[design-brand-guardian]] → 定义了 Brand Foundation Framework 的完整结构
|
||||
- [[Visual-Identity-System]] → Brand Foundation Framework 的视觉表达
|
||||
- [[Brand-Voice]] → Brand Foundation Framework 的语言表达
|
||||
- [[design-ux-architect]] → Brand Foundation Framework 是其技术实现的输入
|
||||
48
wiki/concepts/Brand-Personality-Framework.md
Normal file
48
wiki/concepts/Brand-Personality-Framework.md
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: "Brand Personality Framework"
|
||||
type: concept
|
||||
tags: [brand, ux, design]
|
||||
last_updated: 2026-04-30
|
||||
---
|
||||
|
||||
# 品牌个性框架（Brand Personality Framework）
|
||||
|
||||
## Aliases
|
||||
- Brand Personality
|
||||
- 品牌个性
|
||||
- 品牌声音（Brand Voice）
|
||||
|
||||
## 定义
|
||||
|
||||
品牌个性框架是定义品牌在所有接触点上"如何表达自己"的系统方法——包括语言风格（文案/语气）、视觉风格（颜色/动画/图标）和交互风格（如何响应用户行为）。核心目标是在保持一致性的同时，传达独特的情感连接。
|
||||
|
||||
## 四维个性谱系
|
||||
|
||||
| 情境 | 维度 | 示例 |
|
||||
|------|------|------|
|
||||
| 专业场景 | Professional Context | 简洁、数据驱动、严谨 |
|
||||
| 休闲场景 | Casual Context | 友好、轻松、有温度 |
|
||||
| 错误场景 | Error Context | 幽默化解焦虑、提供清晰引导 |
|
||||
| 成功场景 | Success Context | 热情庆祝、肯定用户成就 |
|
||||
|
||||
## 关键要素
|
||||
|
||||
1. **品牌声音（Brand Voice）**：在各类情境下保持一致的语言风格和语气
|
||||
2. **视觉人格（Visual Personality）**：颜色、动画风格、图标选择等视觉元素的一致性
|
||||
3. **交互风格（Interaction Style）**：系统如何响应用户动作——积极的？稳重的？俏皮的？
|
||||
4. **文化敏感性**：确保个性表达跨越文化边界时不产生误解
|
||||
|
||||
## 与微交互的关系
|
||||
|
||||
微交互是品牌个性在交互层的执行载体——一个"俏皮"的品牌会在微交互中体现俏皮（趣味动画/庆祝效果），一个"专业"的品牌则会选择克制的、精确的反馈。
|
||||
|
||||
## 应用场景
|
||||
|
||||
- [[design-whimsy-injector]] 负责将品牌个性框架转化为具体的趣味性设计规范和微文案
|
||||
- [[design-brand-guardian]] 负责维护品牌个性的一致性和边界
|
||||
|
||||
## 相关概念
|
||||
|
||||
- [[design-whimsy-injector]]：品牌个性框架的具体执行者
|
||||
- [[Micro-Interaction]]：品牌个性在交互细节上的表达
|
||||
- [[Inclusive-Delight]]：品牌个性需兼顾包容性，不能因追求个性而排除特定用户群
|
||||
49
wiki/concepts/Brand-Protection.md
Normal file
49
wiki/concepts/Brand-Protection.md
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: "Brand Protection"
|
||||
type: concept
|
||||
tags: [brand, protection, trademark, governance]
|
||||
last_updated: 2026-05-15
|
||||
sources: [design-brand-guardian]
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
品牌保护是维护品牌完整性、价值和声誉的综合策略体系，包含 Trademark Strategy（商标策略）、Compliance Monitoring（合规监控）和 Crisis Management（危机管理）三个核心维度。
|
||||
|
||||
## Core Components
|
||||
|
||||
### Trademark Strategy（商标策略）
|
||||
- 商标注册和保护计划
|
||||
- 知识产权识别和登记
|
||||
- 侵权监测和执法
|
||||
- 法律保护框架
|
||||
|
||||
### Compliance Monitoring（合规监控）
|
||||
- 品牌使用合规性检查
|
||||
- 品牌实施跨所有触点的监控
|
||||
- 品牌指南遵守情况审计
|
||||
- 纠正性指导机制
|
||||
|
||||
### Crisis Management（危机管理）
|
||||
- 品牌危机应对预案
|
||||
- 声誉保护策略
|
||||
- 利益相关者沟通计划
|
||||
- 品牌恢复路径
|
||||
|
||||
## Key Activities
|
||||
|
||||
- 保护品牌知识产权
|
||||
- 监控品牌一致性实施
|
||||
- 管理品牌危机情况
|
||||
- 确保文化敏感性和市场适当性
|
||||
|
||||
## Brand Protection as Default
|
||||
|
||||
Brand Guardian Agent 将品牌保护作为默认要求内置于所有品牌策略中，而非事后补救。
|
||||
|
||||
## Connections
|
||||
|
||||
- [[design-brand-guardian]] → 定义了 Brand Protection 的完整框架
|
||||
- [[Brand-Foundation-Framework]] → Brand Protection 保护品牌基础框架的完整性
|
||||
- [[Automation-Governance-Architect]] → 共享治理和保护的系统性思维
|
||||
- [[Compliance-Auditor]] → 提供合规监控的方法论参考
|
||||
47
wiki/concepts/Brand-Voice.md
Normal file
47
wiki/concepts/Brand-Voice.md
Normal file
@@ -0,0 +1,47 @@
|
||||
---
|
||||
title: "Brand Voice"
|
||||
type: concept
|
||||
tags: [brand, voice, communication, messaging]
|
||||
last_updated: 2026-05-15
|
||||
sources: [design-brand-guardian]
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
品牌声音是品牌语言表达的核心规范，定义品牌如何与受众沟通。包含 Voice Characteristics（声音特征）、Tone Variations（语气变体）和 Messaging Framework（信息架构）三个维度。
|
||||
|
||||
## Core Components
|
||||
|
||||
### Voice Characteristics（声音特征）
|
||||
定义品牌沟通的人类特征：
|
||||
- **Strategic（战略性）**：强调品牌决策的战略价值
|
||||
- **Consistent（一致性）**：确保跨所有渠道的品牌表达一致
|
||||
- **Protective（保护性）**：维护品牌完整性和价值
|
||||
- **Visionary（愿景性）**：传达品牌的未来导向和雄心
|
||||
|
||||
### Tone Variations（语气变体）
|
||||
根据场景调整的语气指南：
|
||||
- **Professional（专业）**：何时使用及示例语言
|
||||
- **Conversational（对话）**：何时使用及示例语言
|
||||
- **Supportive（支持）**：何时使用及示例语言
|
||||
|
||||
### Messaging Framework（信息架构）
|
||||
- **Brand Tagline**：概括品牌精髓的易记短语
|
||||
- **Value Proposition**：清晰的客户利益声明
|
||||
- **Key Messages**：
|
||||
1. 主要受众的主要信息
|
||||
2. 次要受众的次要信息
|
||||
3. 特定用例的支持信息
|
||||
|
||||
## Writing Guidelines
|
||||
|
||||
- **Vocabulary**：首选术语、需要避免的短语
|
||||
- **Grammar**：风格偏好、格式标准
|
||||
- **Cultural Considerations**：包容性语言指南
|
||||
|
||||
## Connections
|
||||
|
||||
- [[Brand-Foundation-Framework]] → Brand Voice 是其语言表达层
|
||||
- [[design-brand-guardian]] → 定义了 Brand Voice 的完整规范
|
||||
- [[Micro-Interaction]] → Brand Voice 在微交互文案中的应用
|
||||
- [[Brand-Personality-Framework]] → Brand Voice 反映品牌个性
|
||||
44
wiki/concepts/Budget-Variance-Analysis.md
Normal file
44
wiki/concepts/Budget-Variance-Analysis.md
Normal file
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: "Budget Variance Analysis"
|
||||
type: concept
|
||||
tags: ["finance", "budgeting", "variance-analysis"]
|
||||
last_updated: 2026-04-30
|
||||
---
|
||||
|
||||
## Definition
|
||||
预算差异分析是通过比较预算金额（budget_amount）与实际金额（actual_amount）之间的差异（variance），判断预算执行状态的财务管控方法，是预算管理闭环的关键环节。
|
||||
|
||||
## Calculation
|
||||
```
|
||||
variance = budget_amount - actual_amount
|
||||
variance_percentage = (actual_amount - budget_amount) / budget_amount × 100
|
||||
```
|
||||
|
||||
## Status Thresholds
|
||||
| 差异百分比 | 预算状态 |
|
||||
|-----------|---------|
|
||||
| ≤ 5% (正或负) | On Track（正常） |
|
||||
| > 5%（超支） | Over Budget（超支） |
|
||||
| > 5%（节省） | Under Budget（节省） |
|
||||
|
||||
## Core Framework
|
||||
通过 SQL 窗口函数实现：
|
||||
1. **CTE `budget_actuals`**：按部门、类别、季度聚合预算与实际数据
|
||||
2. **CTE `department_summary`**：按部门维度汇总，输出总预算、总实际、差异总额、平均差异百分比
|
||||
|
||||
## Success Criteria
|
||||
预算准确率目标：**95%+**，差异分析需附带差异原因说明和纠正行动计划。
|
||||
|
||||
## Workflow
|
||||
1. 财务数据验证与核对
|
||||
2. 差异计算与状态分类
|
||||
3. 差异解释与根因分析
|
||||
4. 纠正措施制定与执行
|
||||
5. 下期预算调整
|
||||
|
||||
## Implementation
|
||||
参见 [[support-finance-tracker]] 中的年度预算 SQL 查询（`WITH budget_actuals AS ...`）。
|
||||
|
||||
## Related Concepts
|
||||
- [[Cash Flow Forecasting]]：现金流预测与预算管理同为财务规划支柱
|
||||
- [[Financial Risk Assessment]]：差异分析是财务风险预警的重要信号
|
||||
54
wiki/concepts/BudgetPacing.md
Normal file
54
wiki/concepts/BudgetPacing.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: "Budget Pacing"
|
||||
type: concept
|
||||
tags: ["ppc", "budget", "pacing", "google-ads", "paid-media"]
|
||||
sources: ["paid-media-ppc-strategist"]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
预算 Pacing（Budget Pacing）是管理广告日预算消耗速度的策略与模型，确保预算在整个日期范围内（通常一天）均匀消耗，避免早期过快耗尽（错失晚间高转化流量）或过慢消耗（浪费展示份额）。核心目标：**日预算消耗率 95-100%，浪费控制在 5% 以内**。
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Daily Budget Mechanics
|
||||
- Google Ads 将日预算乘以 30.4（平均每月天数）作为月预算
|
||||
- 实际消耗可能在单日波动 ±20%，月度总量不超过月预算
|
||||
|
||||
### Pacing Patterns
|
||||
|
||||
| 模式 | 描述 | 风险 |
|
||||
|------|------|------|
|
||||
| **Accelerated** | 尽快消耗预算 | 早期耗尽，错失后续流量 |
|
||||
| **Standard** | 算法均匀分配 | 通常推荐 |
|
||||
| **Seasonal Adjustment** | 旺季/淡季动态调整 | 需主动管理 |
|
||||
|
||||
## Pacing Analysis
|
||||
|
||||
### Diminishing Returns Analysis
|
||||
- 识别预算边际效益递减点
|
||||
- 测试增量预算的转化效率
|
||||
- 确定最优预算天花板
|
||||
|
||||
### Incremental Spend Testing
|
||||
```
|
||||
Hypothesis：每增加 $X 日预算，可带来 Y 个额外转化
|
||||
Methodology：逐步增加预算 20-30%，监控 CPA 变化
|
||||
Stop criteria：CPA 上升超过 X% 或转化量无显著提升
|
||||
```
|
||||
|
||||
### Seasonal Budget Shifting
|
||||
- **Q4 Holiday Season**：提前 4-6 周增加预算，黑色星期五达到峰值
|
||||
- **Product Launch**：发布前 2 周开始预热，逐步加码
|
||||
- **Off-Peak**：适度降低预算，维持展示份额
|
||||
|
||||
## Success Metrics
|
||||
- 日预算消耗率：95-100%（过高=浪费，过低=错失流量）
|
||||
- 浪费率：<5%
|
||||
- 周末/工作日 pacing 一致性
|
||||
|
||||
## Connections
|
||||
- [[MCCLevelStrategy]]：MCC 级预算分配和 pacing 是多账户协调的核心
|
||||
- [[AutomatedBiddingStrategy]]：自动化竞价需配合充足预算才能发挥最佳效果
|
||||
- [[GoogleAds]]：Budget Pacing 是 Google Ads 账户管理的基本功
|
||||
29
wiki/concepts/BusinessImpactQuantification.md
Normal file
29
wiki/concepts/BusinessImpactQuantification.md
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: "Business Impact Quantification"
|
||||
type: concept
|
||||
tags: ["business-analysis", "consulting", "metrics"]
|
||||
sources: ["support-executive-summary-generator"]
|
||||
last_updated: 2026-04-26
|
||||
---
|
||||
|
||||
## Definition
|
||||
商业影响量化是一种将业务发现和建议转化为具体、可衡量数据的方法论。核心是用 $ 或 % 等定量指标使影响具体可感知，避免模糊表述。
|
||||
|
||||
## Key Principles
|
||||
- **量化优先**：用具体数字替代模糊描述（如"34% QoQ增长"而非"显著增长"）
|
||||
- **财务影响明确**：Revenue/Cost/Market Share 变化必须量化
|
||||
- **风险/机会幅度**：用概率或百分比表达不确定性
|
||||
- **时间范围**：明确影响实现的时间节点
|
||||
|
||||
## Application in Executive Summary
|
||||
- 每个 Key Finding 必须包含 ≥ 1 个量化数据点
|
||||
- Business Impact 部分量化潜在收益/损失
|
||||
- Recommendations 包含预期结果的可衡量指标
|
||||
|
||||
## Examples
|
||||
- "Customer acquisition costs increased 34% QoQ, from $45 to $60 per customer"
|
||||
- "This initiative could unlock $2.3M in annual recurring revenue within 18 months"
|
||||
|
||||
## Related Concepts
|
||||
- [[Executive Summary]]
|
||||
- [[Action-Oriented Recommendations]]
|
||||
38
wiki/concepts/CBT-CognitiveDistortions.md
Normal file
38
wiki/concepts/CBT-CognitiveDistortions.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: "CBT Cognitive Distortions"
|
||||
type: concept
|
||||
tags: []
|
||||
sources: [academic-psychologist]
|
||||
last_updated: 2026-04-25
|
||||
---
|
||||
|
||||
# CBT Cognitive Distortions
|
||||
|
||||
## Aliases
|
||||
- Beck's Cognitive Distortions
|
||||
- Cognitive Distortions
|
||||
- Thinking Errors
|
||||
|
||||
## Definition
|
||||
Beck 认知行为疗法中的认知扭曲——非理性、适应不良的思维模式，驱动情绪反应和行为决策。
|
||||
|
||||
## Common Cognitive Distortions
|
||||
|
||||
| 扭曲类型 | 描述 | 例子 |
|
||||
|----------|------|------|
|
||||
| All-or-Nothing（全或无思维） | 非黑即白的极端判断 | "如果我不完美，就是彻底的失败" |
|
||||
| Overgeneralization（过度概括） | 以单一事件得出普遍结论 | "这次失败了，我永远都会失败" |
|
||||
| Mental Filter（心理过滤） | 放大负面、忽视正面 | 只记住批评，忘记所有赞美 |
|
||||
| Disqualifying the Positive（贬损正面） | 把正面经历解释为偶然 | "他们夸我只是客气" |
|
||||
| Jumping to Conclusions（跳跃式结论） | 无根据的负面解读 | 读心术、预言式思维 |
|
||||
| Magnification/Minimization（放大/缩小） | 不成比例地放大负面、缩小正面 | 把小错误灾难化 |
|
||||
| Emotional Reasoning（情绪化推理） | "我感觉是这样，所以就是这样" | "我觉得自己很蠢，所以我就是蠢" |
|
||||
| Should Statements（"应该"陈述） | 僵化的规则和自我要求 | "我应该总是坚强" |
|
||||
| Labeling（标签化） | 用标签代替行为描述 | "我是一个失败者" |
|
||||
| Personalization（个人化） | 不恰当地把外部事件和自己关联 | "他生气是因为我" |
|
||||
|
||||
## Application in Character Design
|
||||
Psychologist Agent 通过识别角色决策背后的具体认知扭曲，而非泛泛说"他们不理性"，使心理分析具有可操作性。
|
||||
|
||||
## Connection to Wiki
|
||||
- Source: [[academic-psychologist]]
|
||||
41
wiki/concepts/CDC-Change-Data-Capture.md
Normal file
41
wiki/concepts/CDC-Change-Data-Capture.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: "CDC (Change Data Capture)"
|
||||
type: concept
|
||||
tags: [data-engineering, streaming, incremental-pipeline]
|
||||
sources: [engineering-data-engineer]
|
||||
last_updated: 2026-05-02
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
CDC（Change Data Capture，变更数据捕获）是一种从源系统捕获增量变更（插入、更新、删除）的技术，使数据管道无需全量刷新即可同步最新数据，大幅降低计算成本。
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **识别变更**：从源数据库的事务日志（WAL）、时间戳字段或变更追踪表中提取变更记录
|
||||
2. **携带元数据**：每条 CDC 记录携带变更类型（INSERT/UPDATE/DELETE）、变更时间、来源事务 ID
|
||||
3. **幂等写入**：通过主键或变更时间戳实现幂等 upsert（MERGE INTO Delta Lake），确保重新运行安全
|
||||
|
||||
## Benefits
|
||||
|
||||
- **成本节省**：增量处理 vs. 全量刷新，成本降低 90%+
|
||||
- **低延迟**：变更实时捕获，支持分钟级甚至秒级数据刷新
|
||||
- **低影响**：CDC 通常基于数据库日志读取，对源系统影响极小
|
||||
|
||||
## CDC in Medallion Architecture
|
||||
|
||||
- **Bronze 层**：CDC 记录追加写入，保留完整变更历史（append-only）
|
||||
- **Silver 层**：基于变更类型（INSERT=插入, UPDATE=更新, DELETE=标记删除）进行去重和 conform
|
||||
- **Gold 层**：CDC 支持近实时业务指标更新
|
||||
|
||||
## CDC Technologies
|
||||
|
||||
- **Debezium**：开源 CDC 平台，捕获 MySQL/PostgreSQL/MongoDB 等变更并发布到 Kafka
|
||||
- **AWS DMS**（Database Migration Service）：AWS 托管 CDC 解决方案
|
||||
- **Azure Data Factory** CDC 活动：Azure 生态 CDC 工具
|
||||
- **Databricks Auto Loader**：`cloudFiles` 增量摄取 CSV/Parquet/JSON 文件变更
|
||||
|
||||
## Related Concepts
|
||||
- [[Medallion Architecture]]
|
||||
- [[Data Contract]]（CDC 需配合数据契约确保 schema 兼容）
|
||||
- [[Apache Kafka]]（CDC 常用传输层）
|
||||
83
wiki/concepts/CI-CD Pipeline.md
Normal file
83
wiki/concepts/CI-CD Pipeline.md
Normal file
@@ -0,0 +1,83 @@
|
||||
---
|
||||
title: "CI/CD Pipeline"
|
||||
type: concept
|
||||
tags: [DevOps, Automation, Software Delivery]
|
||||
sources: [engineering-devops-automator]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
# CI/CD Pipeline
|
||||
|
||||
## 定义
|
||||
CI/CD 流水线是自动化软件交付的端到端管道，包含持续集成（Continuous Integration）、持续交付（Continuous Delivery）和持续部署（Continuous Deployment）三个阶段。
|
||||
|
||||
## 三个阶段
|
||||
|
||||
### 持续集成（CI）
|
||||
- 开发者频繁提交代码到共享仓库
|
||||
- 每次提交自动触发构建和测试
|
||||
- 早期发现集成问题
|
||||
|
||||
### 持续交付（CD）
|
||||
- 代码通过所有自动化测试后自动部署到 staging 环境
|
||||
- 人工审批后部署到生产环境
|
||||
- 确保每次变更都可部署
|
||||
|
||||
### 持续部署（Continuous Deployment）
|
||||
- 代码通过所有测试后自动部署到生产环境
|
||||
- 无需人工干预
|
||||
- 需要完善的测试和监控体系支撑
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 构建阶段
|
||||
- 代码编译
|
||||
- 依赖安装
|
||||
- 制品构建（Docker 镜像/二进制文件）
|
||||
|
||||
### 测试阶段
|
||||
- 单元测试
|
||||
- 集成测试
|
||||
- 端到端测试
|
||||
- 安全扫描
|
||||
|
||||
### 部署阶段
|
||||
- 部署到目标环境
|
||||
- 健康检查
|
||||
- 流量切换
|
||||
- 回滚机制
|
||||
|
||||
## DevOps Automator 的标准流水线
|
||||
```yaml
|
||||
security-scan → test → build → deploy
|
||||
```
|
||||
- security-scan：依赖漏洞扫描 + 静态安全分析
|
||||
- test：单元测试 + 集成测试
|
||||
- build：容器构建 + 推送镜像仓库
|
||||
- deploy：零停机部署（蓝绿/金丝雀/滚动）
|
||||
|
||||
## 相关工具
|
||||
- [[GitHub Actions]]：DevOps Automator 默认选择
|
||||
- Jenkins：开源 CI/CD 服务器
|
||||
- GitLab CI：GitLab 内置 CI/CD
|
||||
- ArgoCD：GitOps 持续交付
|
||||
- Spinnaker：多云持续交付平台
|
||||
|
||||
## 相关概念
|
||||
- [[Infrastructure as Code]]：CI/CD 部署目标通常是 IaC 管理的基础设施
|
||||
- [[Zero-Downtime Deployment]]：CI/CD 的部署策略
|
||||
- [[Blue-Green Deployment]]：CI/CD 常用部署策略
|
||||
|
||||
## 关键指标
|
||||
- **部署频率**：每日部署次数
|
||||
- **变更前置时间**：代码提交到生产的时间
|
||||
- **变更失败率**：生产环境回滚或失败的百分比
|
||||
- **MTTR**：平均恢复时间
|
||||
|
||||
## Aliases
|
||||
- CI/CD
|
||||
- CI/CD Pipeline
|
||||
- 持续集成/持续交付
|
||||
- Continuous Integration
|
||||
- Continuous Delivery
|
||||
- Continuous Deployment
|
||||
@@ -1,51 +1,51 @@
|
||||
---
|
||||
title: "CI/CD Pipeline"
|
||||
type: concept
|
||||
sources: [ctp-topic-1-gruntwork-landing-zone-architecture, ctp-topic-9-ci-cd-with-gruntwork]
|
||||
last_updated: 2026-04-14
|
||||
---
|
||||
|
||||
## Definition
|
||||
CI/CD 流水线（CI/CD Pipeline）是持续集成（Continuous Integration）和持续交付/部署（Continuous Delivery/Deployment）的自动化流程，用于管理基础设施代码（IaC）的构建、测试和部署。在 Gruntwork Landing Zone 架构中，每个 Landing Zone 配置独立的 Jenkins 服务器和 CI/CD 流水线来自动化 Terraform 基础设施变更。
|
||||
|
||||
## Core Components
|
||||
|
||||
### CI（持续集成）
|
||||
- **代码提交**：开发人员将特性分支代码推送到 GitHub 仓库
|
||||
- **自动构建**：Jenkins 触发 Terraform 初始化和格式化验证
|
||||
- **自动测试**：TerraTest 执行基础设施单元测试和集成测试
|
||||
- **代码审查**：Pull Request 必须通过审查才能合并到主分支
|
||||
|
||||
### CD（持续交付/部署）
|
||||
- **自动部署**：合并到主分支后，Jenkins 自动执行 Terraform Plan
|
||||
- **审批流程**：变更需要人工审批后才执行 Apply
|
||||
- **渐进式部署**：支持 Blue-Green 部署和 Canary Release 策略
|
||||
|
||||
### Infrastructure-Specific Considerations
|
||||
- **状态管理**：Terraform State 的锁定和远程存储（使用 S3 + DynamoDB）
|
||||
- **幂等性**：Terraform 模块设计必须支持重复执行而不产生副作用
|
||||
- **回滚机制**：通过 Terraform State 历史版本实现快速回滚
|
||||
- **漂移检测**：定期运行 `terraform plan` 检测配置漂移
|
||||
|
||||
## Tools in Gruntwork Landing Zone Context
|
||||
- **Jenkins**：核心 CI/CD 引擎，每个 Landing Zone 独立部署
|
||||
- **Terraform**：IaC 工具，定义和管理 AWS 资源
|
||||
- **TerraTest**：Go 语言编写的基础设施测试框架
|
||||
- **GitHub**：代码仓库，支持特性分支和 Pull Request 工作流
|
||||
|
||||
## Git Workflow
|
||||
- 特性分支开发：`feature/<description>`
|
||||
- 通过 Pull Request 合并到主分支
|
||||
- 必须经过代码审查和 CI 测试
|
||||
- 合并后触发自动部署流水线
|
||||
|
||||
## Related Concepts
|
||||
- [[Landing-Zone-Architecture]]：CI/CD 流水线是 Landing Zone 自动化运维的核心机制
|
||||
- [[Terraform-Modules]]：被 CI/CD 流水线自动化部署的 IaC 模块
|
||||
- [[GitOps]]：基于 Git 的运维方式，CI/CD 是其技术实现
|
||||
- [[TerraTest]]：用于基础设施变更的自动化测试工具
|
||||
|
||||
## References
|
||||
- [[ctp-topic-1-gruntwork-landing-zone-architecture]]
|
||||
- [[ctp-topic-9-ci-cd-with-gruntwork]]
|
||||
- [[ctp-topic-2-git]]
|
||||
---
|
||||
title: "CI/CD Pipeline"
|
||||
type: concept
|
||||
sources: [ctp-topic-1-gruntwork-landing-zone-architecture, ctp-topic-9-ci-cd-with-gruntwork, engineering-devops-automator]
|
||||
last_updated: 2026-04-14
|
||||
---
|
||||
|
||||
## Definition
|
||||
CI/CD 流水线（CI/CD Pipeline）是持续集成（Continuous Integration）和持续交付/部署（Continuous Delivery/Deployment）的自动化流程，用于管理基础设施代码（IaC）的构建、测试和部署。在 Gruntwork Landing Zone 架构中，每个 Landing Zone 配置独立的 Jenkins 服务器和 CI/CD 流水线来自动化 Terraform 基础设施变更。
|
||||
|
||||
## Core Components
|
||||
|
||||
### CI（持续集成）
|
||||
- **代码提交**：开发人员将特性分支代码推送到 GitHub 仓库
|
||||
- **自动构建**：Jenkins 触发 Terraform 初始化和格式化验证
|
||||
- **自动测试**：TerraTest 执行基础设施单元测试和集成测试
|
||||
- **代码审查**：Pull Request 必须通过审查才能合并到主分支
|
||||
|
||||
### CD（持续交付/部署）
|
||||
- **自动部署**：合并到主分支后，Jenkins 自动执行 Terraform Plan
|
||||
- **审批流程**：变更需要人工审批后才执行 Apply
|
||||
- **渐进式部署**：支持 Blue-Green 部署和 Canary Release 策略
|
||||
|
||||
### Infrastructure-Specific Considerations
|
||||
- **状态管理**：Terraform State 的锁定和远程存储（使用 S3 + DynamoDB）
|
||||
- **幂等性**：Terraform 模块设计必须支持重复执行而不产生副作用
|
||||
- **回滚机制**：通过 Terraform State 历史版本实现快速回滚
|
||||
- **漂移检测**：定期运行 `terraform plan` 检测配置漂移
|
||||
|
||||
## Tools in Gruntwork Landing Zone Context
|
||||
- **Jenkins**：核心 CI/CD 引擎，每个 Landing Zone 独立部署
|
||||
- **Terraform**：IaC 工具，定义和管理 AWS 资源
|
||||
- **TerraTest**：Go 语言编写的基础设施测试框架
|
||||
- **GitHub**：代码仓库，支持特性分支和 Pull Request 工作流
|
||||
|
||||
## Git Workflow
|
||||
- 特性分支开发：`feature/<description>`
|
||||
- 通过 Pull Request 合并到主分支
|
||||
- 必须经过代码审查和 CI 测试
|
||||
- 合并后触发自动部署流水线
|
||||
|
||||
## Related Concepts
|
||||
- [[Landing-Zone-Architecture]]：CI/CD 流水线是 Landing Zone 自动化运维的核心机制
|
||||
- [[Terraform-Modules]]：被 CI/CD 流水线自动化部署的 IaC 模块
|
||||
- [[GitOps]]：基于 Git 的运维方式，CI/CD 是其技术实现
|
||||
- [[TerraTest]]：用于基础设施变更的自动化测试工具
|
||||
|
||||
## References
|
||||
- [[ctp-topic-1-gruntwork-landing-zone-architecture]]
|
||||
- [[ctp-topic-9-ci-cd-with-gruntwork]]
|
||||
- [[ctp-topic-2-git]]
|
||||
|
||||
28
wiki/concepts/CORS-Allowlist.md
Normal file
28
wiki/concepts/CORS-Allowlist.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: "CORS-Allowlist"
|
||||
type: concept
|
||||
tags: []
|
||||
sources: [expose-hermes-agent-as-an-openai-compatible-api-for-any-frontend]
|
||||
last_updated: 2026-05-02
|
||||
---
|
||||
|
||||
## Definition
|
||||
CORS Allowlist（跨域资源共享白名单）是一种浏览器安全机制，通过精确配置允许特定来源的跨域请求。
|
||||
|
||||
## Purpose
|
||||
当浏览器中的前端应用（如 Open WebUI）调用不同域的后端 API 时，浏览器会先发送预检请求（OPTIONS），服务器需明确允许该来源才能放行。
|
||||
|
||||
## Configuration in Hermes Agent
|
||||
Hermes Agent API Server 支持 CORS Allowlist 配置：
|
||||
- **环境变量**：`CORS_ALLOWED_ORIGINS` 设置允许的域名列表
|
||||
- **默认值**：仅允许配置列表中的来源
|
||||
- **安全建议**：生产环境仅开放必要的域名
|
||||
|
||||
## Example
|
||||
```
|
||||
CORS_ALLOWED_ORIGINS=https://app.openwebui.com,https://chat.example.com
|
||||
```
|
||||
|
||||
## Related
|
||||
- [[OpenAI-Compatible-API]]
|
||||
- [[hermes-agent]]（via Hermes-Agent.md）
|
||||
92
wiki/concepts/CSS-Design-System.md
Normal file
92
wiki/concepts/CSS-Design-System.md
Normal file
@@ -0,0 +1,92 @@
|
||||
---
|
||||
title: "CSS Design System"
|
||||
type: concept
|
||||
tags: [css, design-system, frontend, architecture]
|
||||
sources: [design-ux-architect.md]
|
||||
last_updated: 2026-04-24
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
CSS Design System 是一套结构化的 CSS 架构规范，通过 CSS Custom Properties（CSS 变量）定义颜色、排版、间距等基础设计 Token，供整个项目复用，确保视觉一致性和主题切换能力。
|
||||
|
||||
## Core Components
|
||||
|
||||
### Color System
|
||||
```css
|
||||
:root {
|
||||
/* Light Theme Colors */
|
||||
--bg-primary: [spec-light-bg];
|
||||
--bg-secondary: [spec-light-secondary];
|
||||
--text-primary: [spec-light-text];
|
||||
--text-secondary: [spec-light-text-muted];
|
||||
--border-color: [spec-light-border];
|
||||
|
||||
/* Brand Colors */
|
||||
--primary-color: [spec-primary];
|
||||
--secondary-color: [spec-secondary];
|
||||
--accent-color: [spec-accent];
|
||||
}
|
||||
```
|
||||
|
||||
### Typography Scale
|
||||
```css
|
||||
:root {
|
||||
--text-xs: 0.75rem; /* 12px */
|
||||
--text-sm: 0.875rem; /* 14px */
|
||||
--text-base: 1rem; /* 16px */
|
||||
--text-lg: 1.125rem; /* 18px */
|
||||
--text-xl: 1.25rem; /* 20px */
|
||||
--text-2xl: 1.5rem; /* 24px */
|
||||
--text-3xl: 1.875rem; /* 30px */
|
||||
}
|
||||
```
|
||||
|
||||
### Spacing System
|
||||
```css
|
||||
:root {
|
||||
--space-1: 0.25rem; /* 4px */
|
||||
--space-2: 0.5rem; /* 8px */
|
||||
--space-4: 1rem; /* 16px */
|
||||
--space-6: 1.5rem; /* 24px */
|
||||
--space-8: 2rem; /* 32px */
|
||||
--space-12: 3rem; /* 48px */
|
||||
--space-16: 4rem; /* 64px */
|
||||
}
|
||||
```
|
||||
|
||||
## Theme Support
|
||||
|
||||
CSS Design System 必须原生支持三种主题模式：
|
||||
|
||||
- **Light Theme**：浅色背景，深色文字
|
||||
- **Dark Theme**：深色背景，浅色文字
|
||||
- **System Theme**：`prefers-color-scheme` 检测系统偏好
|
||||
|
||||
```css
|
||||
[data-theme="dark"] {
|
||||
--bg-primary: [spec-dark-bg];
|
||||
--bg-secondary: [spec-dark-secondary];
|
||||
--text-primary: [spec-dark-text];
|
||||
--text-secondary: [spec-dark-text-muted];
|
||||
--border-color: [spec-dark-border];
|
||||
}
|
||||
|
||||
@media (prefers-color-scheme: dark) {
|
||||
:root:not([data-theme="light"]) {
|
||||
--bg-primary: [spec-dark-bg];
|
||||
/* ... */
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Related Concepts
|
||||
|
||||
- [[Theme-Toggle]]：主题切换交互组件
|
||||
- [[Theme-Manager]]：JavaScript 主题管理类
|
||||
- [[Layout-Framework]]：基于此系统的布局架构
|
||||
- [[Component-Architecture]]：组件样式规范
|
||||
|
||||
## Sources
|
||||
|
||||
- [[design-ux-architect]] — CSS Design System 的完整定义和示例代码
|
||||
55
wiki/concepts/CTV-OTT-Advertising.md
Normal file
55
wiki/concepts/CTV-OTT-Advertising.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: "CTV/OTT Advertising"
|
||||
type: concept
|
||||
tags: ["ctv", "ott", "streaming", "paid-media", "video"]
|
||||
sources: ["paid-media-programmatic-buyer"]
|
||||
last_updated: 2026-04-26
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
CTV/OTT Advertising（Connected TV / Over-the-Top Advertising）是指在联网电视设备和流媒体服务上投放的视频广告形式。CTV（Connected TV）指通过互联网连接的消费设备（如 Smart TV、Roku、Amazon Fire TV、Apple TV），OTT（Over-the-Top）指通过互联网直接传输到设备的视频内容订阅服务（如 Netflix、Hulu、Disney+ 等）。
|
||||
|
||||
## CTV vs OTT
|
||||
|
||||
| 类型 | 设备/平台 | 内容传输方式 |
|
||||
|------|---------|------------|
|
||||
| CTV | Smart TV、Roku、Fire TV、Apple TV | 设备通过互联网接收内容 |
|
||||
| OTT | 独立应用（Netflix、Hulu 等） | 直接通过互联网传输到任何设备 |
|
||||
|
||||
## Ad Formats
|
||||
|
||||
- **Pre-roll**：在流媒体内容播放前展示（最常见）
|
||||
- **Mid-roll**：在内容中途插入，类似于传统电视广告时段
|
||||
- **Post-roll**：在内容结束后展示
|
||||
- **Pause Ads**：用户暂停播放时展示的全屏广告
|
||||
- **Display Overlay**：视频播放时的底部横幅展示
|
||||
|
||||
## Buying Methods
|
||||
|
||||
- **Programmatic Direct**：通过程序化直接预订优质流媒体库存
|
||||
- **Private Marketplace（PMP）**：与特定流媒体平台建立私有交易
|
||||
- **Open Exchange**：公开程序化竞价购买 CTV 库存
|
||||
|
||||
## Key Metrics
|
||||
|
||||
- **Impression Share**：广告展示占可寻址库存的比例
|
||||
- **Completion Rate**：视频广告完整播放率（目标 ≥80%）
|
||||
- **Viewability Rate**：联网电视 MRC 标准（50% 像素可见 2 秒）
|
||||
- **Audible Rate**：音频被激活的展示比例（视频广告）
|
||||
- ** household Coverage**：触达的家庭单位数量
|
||||
|
||||
## Why CTV/OTT for Brand Extension
|
||||
|
||||
- **传统电视的数字化延伸**：以程序化方式触达线性电视受众
|
||||
- **优质内容环境**：流媒体内容的品牌安全性和可见性通常高于数字展示
|
||||
- **高级定向能力**：超越传统电视的人口统计定向，实现行为和意图定向
|
||||
- **跨设备归因**：结合数字展示和CTV数据构建更完整的受众画像
|
||||
|
||||
## Related Concepts
|
||||
- [[Programmatic Buying]]
|
||||
- [[Viewability]]
|
||||
- [[Frequency Cap]]
|
||||
|
||||
## Sources
|
||||
- [[paid-media-programmatic-buyer]]
|
||||
@@ -1,78 +1,80 @@
|
||||
---
|
||||
title: "Calibration Testing"
|
||||
type: concept
|
||||
tags: [model-evaluation, probability-calibration, model-quality]
|
||||
last_updated: 2026-04-25
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
概率校准（Calibration Testing）验证模型输出的预测概率与实际发生的频率是否一致。一个校准良好的分类器：若它预测某事件概率为 80%，则该事件实际发生的频率应接近 80%。
|
||||
|
||||
## Core Methods
|
||||
|
||||
### Hosmer-Lemeshow Test
|
||||
- 将预测概率分组（默认10组），比较每组观测正例数与期望正例数
|
||||
- 统计量：$\chi^2 = \sum \frac{(observed - expected)^2}{expected(1 - expected/n)}$
|
||||
- 自由度：组数 - 2；p-value < 0.05 → 拒绝原假设（校准差）
|
||||
- **局限性**：对样本量敏感，分组方式不同结果不同
|
||||
|
||||
### Brier Score
|
||||
- $BS = \frac{1}{N}\sum(p_i - y_i)^2$，取值 [0, 0.25]（二分类）
|
||||
- 同时衡量校准（calibration）和区分度（refinement）
|
||||
- 值越低越好，可分解为：$BS = Calibration^2 + Refinement$
|
||||
- **优势**：无需分组，对样本量稳健，可跨模型比较
|
||||
|
||||
### Reliability Diagram（可靠性图）
|
||||
- 将预测概率分箱（bin），绘制实际正例率 vs 预测概率
|
||||
- 理想情况为 45° 对角线；S 形曲线表示欠/过度预测
|
||||
- 视觉诊断工具，适合识别系统性校准偏差
|
||||
|
||||
### Expected Calibration Error (ECE)
|
||||
- 加权平均每箱预测概率与实际频率的绝对差
|
||||
- $ECE = \sum_b \frac{|b|}{n} |acc(b) - conf(b)|$
|
||||
- 量化校准误差，便于跨模型对比
|
||||
|
||||
## Usage
|
||||
|
||||
```python
|
||||
# Hosmer-Lemeshow
|
||||
from scipy.stats import chi2
|
||||
|
||||
def hosmer_lemshow_test(y_true, y_pred, groups=10):
|
||||
data = pd.DataFrame({"y": y_true, "p": y_pred})
|
||||
data["bucket"] = pd.qcut(data["p"], groups, duplicates="drop")
|
||||
agg = data.groupby("bucket", observed=True).agg(
|
||||
n=("y", "count"), observed=("y", "sum"), expected=("p", "sum")
|
||||
)
|
||||
hl_stat = (((agg["observed"] - agg["expected"])**2) /
|
||||
(agg["expected"] * (1 - agg["expected"]/agg["n"]))).sum()
|
||||
dof = len(agg) - 2
|
||||
p_value = 1 - chi2.cdf(hl_stat, dof)
|
||||
return {"HL_statistic": round(hl_stat, 4), "p_value": round(p_value, 6), "calibrated": p_value >= 0.05}
|
||||
|
||||
# Brier Score
|
||||
from sklearn.metrics import brier_score_loss
|
||||
bs = brier_score_loss(y_true, y_pred)
|
||||
```
|
||||
|
||||
## Model QA 中的应用
|
||||
|
||||
Model QA Specialist 执行以下校准审计：
|
||||
1. **跨子群体校准**：在年龄/地区/收入等子群体上分别测试，发现整体指标掩盖的局部校准问题
|
||||
2. **时间窗口稳定性**：跨 OOT（Out-of-Time）窗口测试校准稳定性，识别时间漂移
|
||||
3. **分布偏移下的校准**：在压力场景（population shift）下测试，评估模型鲁棒性
|
||||
4. **决策阈值校准**：根据业务决策阈值（如 p > 0.6 触发行动），评估该阈值处的校准质量
|
||||
|
||||
## Relationship
|
||||
|
||||
- **依赖** [[Discrimination-Metrics]]：先验证模型有区分能力（AUC/Gini），再讨论校准才有意义
|
||||
- **依赖** [[SHAP]]：SHAP 解释"哪个特征导致校准偏差"，支撑诊断方向
|
||||
- **依赖** [[Population-Stability-Index]]：PSI 捕捉特征分布漂移，漂移是校准失效的根本原因之一
|
||||
- **支撑** [[specialized-model-qa]]（Source）：Model QA Specialist 的核心审计步骤之一
|
||||
|
||||
## Key Insights
|
||||
|
||||
- **High AUC ≠ Well Calibrated**：模型可以高区分度但低校准（如逻辑回归自然校准，神经网络往往过度自信）
|
||||
- **业务影响**：校准误差 180bps（0.18）在 decile 10 可能影响 12% 的资产组合
|
||||
- **监管要求**：巴塞尔协议/IFRS 9/CCAR 等监管框架明确要求信用风险模型的概率校准
|
||||
---
|
||||
title: "Calibration Testing"
|
||||
type: concept
|
||||
tags: [model-evaluation, probability-calibration, model-quality]
|
||||
sources:
|
||||
- specialized-model-qa
|
||||
last_updated: 2026-05-29
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
概率校准（Calibration Testing）验证模型输出的预测概率与实际发生的频率是否一致。一个校准良好的分类器：若它预测某事件概率为 80%，则该事件实际发生的频率应接近 80%。
|
||||
|
||||
## Core Methods
|
||||
|
||||
### Hosmer-Lemeshow Test
|
||||
- 将预测概率分组（默认10组），比较每组观测正例数与期望正例数
|
||||
- 统计量：$\chi^2 = \sum \frac{(observed - expected)^2}{expected(1 - expected/n)}$
|
||||
- 自由度：组数 - 2；p-value < 0.05 → 拒绝原假设（校准差）
|
||||
- **局限性**：对样本量敏感，分组方式不同结果不同
|
||||
|
||||
### Brier Score
|
||||
- $BS = \frac{1}{N}\sum(p_i - y_i)^2$，取值 [0, 0.25]（二分类）
|
||||
- 同时衡量校准（calibration）和区分度（refinement）
|
||||
- 值越低越好，可分解为：$BS = Calibration^2 + Refinement$
|
||||
- **优势**：无需分组，对样本量稳健，可跨模型比较
|
||||
|
||||
### Reliability Diagram（可靠性图）
|
||||
- 将预测概率分箱（bin），绘制实际正例率 vs 预测概率
|
||||
- 理想情况为 45° 对角线；S 形曲线表示欠/过度预测
|
||||
- 视觉诊断工具，适合识别系统性校准偏差
|
||||
|
||||
### Expected Calibration Error (ECE)
|
||||
- 加权平均每箱预测概率与实际频率的绝对差
|
||||
- $ECE = \sum_b \frac{|b|}{n} |acc(b) - conf(b)|$
|
||||
- 量化校准误差，便于跨模型对比
|
||||
|
||||
## Usage
|
||||
|
||||
```python
|
||||
# Hosmer-Lemeshow
|
||||
from scipy.stats import chi2
|
||||
|
||||
def hosmer_lemshow_test(y_true, y_pred, groups=10):
|
||||
data = pd.DataFrame({"y": y_true, "p": y_pred})
|
||||
data["bucket"] = pd.qcut(data["p"], groups, duplicates="drop")
|
||||
agg = data.groupby("bucket", observed=True).agg(
|
||||
n=("y", "count"), observed=("y", "sum"), expected=("p", "sum")
|
||||
)
|
||||
hl_stat = (((agg["observed"] - agg["expected"])**2) /
|
||||
(agg["expected"] * (1 - agg["expected"]/agg["n"]))).sum()
|
||||
dof = len(agg) - 2
|
||||
p_value = 1 - chi2.cdf(hl_stat, dof)
|
||||
return {"HL_statistic": round(hl_stat, 4), "p_value": round(p_value, 6), "calibrated": p_value >= 0.05}
|
||||
|
||||
# Brier Score
|
||||
from sklearn.metrics import brier_score_loss
|
||||
bs = brier_score_loss(y_true, y_pred)
|
||||
```
|
||||
|
||||
## Model QA 中的应用
|
||||
|
||||
Model QA Specialist 执行以下校准审计：
|
||||
1. **跨子群体校准**：在年龄/地区/收入等子群体上分别测试，发现整体指标掩盖的局部校准问题
|
||||
2. **时间窗口稳定性**：跨 OOT（Out-of-Time）窗口测试校准稳定性，识别时间漂移
|
||||
3. **分布偏移下的校准**：在压力场景（population shift）下测试，评估模型鲁棒性
|
||||
4. **决策阈值校准**：根据业务决策阈值（如 p > 0.6 触发行动），评估该阈值处的校准质量
|
||||
|
||||
## Relationship
|
||||
|
||||
- **依赖** [[Discrimination-Metrics]]：先验证模型有区分能力（AUC/Gini），再讨论校准才有意义
|
||||
- **依赖** [[SHAP]]：SHAP 解释"哪个特征导致校准偏差"，支撑诊断方向
|
||||
- **依赖** [[Population-Stability-Index]]：PSI 捕捉特征分布漂移，漂移是校准失效的根本原因之一
|
||||
- **支撑** [[specialized-model-qa]]（Source）：Model QA Specialist 的核心审计步骤之一
|
||||
|
||||
## Key Insights
|
||||
|
||||
- **High AUC ≠ Well Calibrated**：模型可以高区分度但低校准（如逻辑回归自然校准，神经网络往往过度自信）
|
||||
- **业务影响**：校准误差 180bps（0.18）在 decile 10 可能影响 12% 的资产组合
|
||||
- **监管要求**：巴塞尔协议/IFRS 9/CCAR 等监管框架明确要求信用风险模型的概率校准
|
||||
|
||||
34
wiki/concepts/Cash-Flow-Forecasting.md
Normal file
34
wiki/concepts/Cash-Flow-Forecasting.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: "Cash Flow Forecasting"
|
||||
type: concept
|
||||
tags: ["finance", "forecasting", "liquidity"]
|
||||
last_updated: 2026-04-30
|
||||
---
|
||||
|
||||
## Definition
|
||||
现金流预测是通过历史模式分析和季节性因子，对企业未来若干期（通常为 12 期滚动）的现金收支进行量化预测的过程，旨在维持流动性并优化资金使用效率。
|
||||
|
||||
## Core Components
|
||||
- **历史模式分析**：按月聚合 receipts（收款）、payments（付款）、net_cash_flow（净现金流）的均值和标准差
|
||||
- **季节性因子**：针对不同月份应用季节性调整系数，反映周期性波动
|
||||
- **增长因子**：根据业务增长趋势调整预测基准
|
||||
- **置信区间**：通常设置 ±15% 的置信区间（如 net_cash_flow × 0.85 / 1.15）
|
||||
|
||||
## Key Metrics
|
||||
- **累积现金**（cumulative_cash）：当前现金余额 + 预测期净现金流之和
|
||||
- **低现金预警**：累积现金 < $50,000 时触发，行动建议为加速收款或延迟付款
|
||||
- **高现金机会**：累积现金 > $200,000 时触发，建议考虑短期投资或预付费用
|
||||
|
||||
## Payment Timing Optimization
|
||||
根据以下公式计算支付优先级分数：
|
||||
```
|
||||
priority_score = early_pay_discount × amount × 365 / payment_terms
|
||||
```
|
||||
优先处理高折扣机会，同时维持现金流健康。
|
||||
|
||||
## Implementation
|
||||
参见 [[support-finance-tracker]] 中 `CashFlowManager` Python 类的实现。
|
||||
|
||||
## Related Concepts
|
||||
- [[Budget Variance Analysis]]：与现金流预测同为财务规划核心工具
|
||||
- [[ROI]]：投资回报评估与现金流优化相互关联
|
||||
72
wiki/concepts/Certora.md
Normal file
72
wiki/concepts/Certora.md
Normal file
@@ -0,0 +1,72 @@
|
||||
---
|
||||
title: "Certora（形式化验证工具）"
|
||||
type: concept
|
||||
tags: [blockchain, security, smart-contract, formal-verification, tooling]
|
||||
sources: [blockchain-security-auditor]
|
||||
last_updated: 2026-05-30
|
||||
---
|
||||
|
||||
## Aliases
|
||||
- Certora
|
||||
- Certora Prover
|
||||
- Certora Verification System
|
||||
|
||||
## Definition
|
||||
|
||||
Certora 是一个基于符号执行（Symbolic Execution）的智能合约形式化验证工具，通过 CVL（Certora Verification Language）描述协议规范，系统性证明 Solidity 合约的关键属性是否在所有可能状态下成立。与测试不同，Certora 可以证明某个属性**在数学上不可能被违反**。
|
||||
|
||||
## Key Capabilities
|
||||
|
||||
- **属性证明**：验证合约不变性（invariant）在所有执行路径上成立
|
||||
- **反例生成**：当属性无法被证明时，自动生成导致属性失败的最小执行序列
|
||||
- **多合约分析**：支持分析调用关系复杂的合约系统
|
||||
- **并行验证**：可并行验证多条规则
|
||||
|
||||
## CVL Example
|
||||
|
||||
```
|
||||
rule noUnauthorizedWithdrawal(method f) {
|
||||
env e;
|
||||
calldataarg args;
|
||||
|
||||
require f != nop; // 排除空调用
|
||||
|
||||
// 如果调用成功，则调用者必须是所有者
|
||||
f(e, args);
|
||||
assert e.msg.sender == owner, "Unauthorized withdrawal";
|
||||
}
|
||||
|
||||
invariant totalSupplyInvariant() {
|
||||
// 总供应量恒定
|
||||
invariant totalSupply == init(totalSupply);
|
||||
}
|
||||
```
|
||||
|
||||
## Integration with Foundry
|
||||
|
||||
Certora 可与 Foundry 集成：
|
||||
```bash
|
||||
# 使用 Halmos 进行字节码级验证
|
||||
forge test --match-contract CertoraTest
|
||||
|
||||
# 使用 Certora CLI
|
||||
certora Run Vault.spec Vault.sol --prover z3 cvc5
|
||||
```
|
||||
|
||||
## Limitations
|
||||
|
||||
- 需要人工编写精确的 CVL 规范（规范本身可能出错）
|
||||
- 复杂合约状态空间可能导致超时
|
||||
- 对外部依赖和链上状态处理有限
|
||||
- 学习曲线陡峭
|
||||
|
||||
## Relationship to Audit
|
||||
|
||||
- Certora 是 [[Blockchain-Security-Auditor]] 进行 [[Formal-Verification]] 的主要工具
|
||||
- 适合验证关键协议属性：份额不变性、借贷健康度、权限不变性
|
||||
- 与 [[Slither]] 互补：Slither 找代码模式漏洞，Certora 证明数学属性
|
||||
|
||||
## Connections
|
||||
- [[Blockchain-Security-Auditor]] ← uses ← [[Certora]]
|
||||
- [[Formal-Verification]] ← implements ← [[Certora]]
|
||||
- [[Halmos]] ← complementary bytecode verification ← [[Certora]]
|
||||
58
wiki/concepts/ChalkboardStyle.md
Normal file
58
wiki/concepts/ChalkboardStyle.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: "ChalkboardStyle"
|
||||
type: concept
|
||||
tags: ["ai-image", "visual-style", "prompt-engineering"]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Chalkboard Style（黑板粉笔风格）是一种复古手绘视觉风格，通过深绿黑背景、手绘粉笔线条、严格限制的 6 色配色盘和木框边框实现统一的视觉氛围，常用于 AI 信息图设计。
|
||||
|
||||
## Visual Specifications
|
||||
|
||||
### Background
|
||||
- 颜色：#1C2B1C（深绿黑色）
|
||||
- 纹理：粉笔灰痕迹、细微划痕、橡皮擦涂抹痕迹
|
||||
|
||||
### Color Palette（严格限制 6 色）
|
||||
| 颜色 | Hex 值 | 用途 |
|
||||
|------|--------|------|
|
||||
| 粉笔白 | #F5F5F5 | 主要文字、轮廓线 |
|
||||
| 粉笔黄 | #FFE566 | 高亮、下划线、强调 |
|
||||
| 粉笔粉 | #FF9999 | 次级高亮、图标 |
|
||||
| 粉笔蓝 | #66B3FF | 图表、技术元素 |
|
||||
| 粉笔绿 | #90EE90 | 成功、自然、正面 |
|
||||
| 粉笔橙 | #FFB366 | 警告、能量 |
|
||||
|
||||
### Lines & Typography
|
||||
- 所有线条必须手绘、速写式（slightly wavy/imperfect）
|
||||
- 禁止完美几何形状
|
||||
- 禁止渐变效果
|
||||
- 禁止数字感强的字体
|
||||
|
||||
### Frame & Decoration
|
||||
- 木框边框（hand-drawn wood grain 线条）
|
||||
- 手绘星星（5-7 点，不规则）
|
||||
- 手绘下划线（波浪形）
|
||||
- 手绘箭头（速写式）
|
||||
- 手绘圆形围绕关键词
|
||||
- 手绘对勾标记
|
||||
- 散落粉笔灰粒子
|
||||
|
||||
### Prohibited Elements
|
||||
- NO gradients（禁止渐变）
|
||||
- NO perfect geometric shapes（禁止完美几何形状）
|
||||
- NO photorealistic elements（禁止写实元素）
|
||||
- NO clean digital vectors（禁止干净的数字矢量）
|
||||
|
||||
## Application
|
||||
|
||||
在 AI 图片生成提示词中使用时，需要：
|
||||
1. 在 [[StyleSeed]] 中定义完整的视觉参数
|
||||
2. 在 [[StyleLock]] 中添加逐项检查清单
|
||||
3. 通过 hex 色值消除颜色描述的歧义
|
||||
|
||||
## Sources
|
||||
|
||||
- [[如何让AI生成风格一致的图片]]
|
||||
54
wiki/concepts/Champion-Challenger.md
Normal file
54
wiki/concepts/Champion-Challenger.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: "Champion-Challenger Framework"
|
||||
type: concept
|
||||
tags: [model-evaluation, model-deployment, champion-challenger, model-governance]
|
||||
sources:
|
||||
- specialized-model-qa
|
||||
last_updated: 2026-05-29
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Champion-Challenger 框架（冠军-挑战者框架）是一种系统化的模型替代评估方法：在生产环境保持当前模型（Champion）运行的同时，引入新候选模型（Challenger）并行评分，通过量化对比决定是否将 Challenger 升级为新的 Champion。核心目标：在保证业务稳定性的前提下，以数据驱动的方式持续提升模型质量。
|
||||
|
||||
## Core Mechanics
|
||||
|
||||
### Shadow Mode Deployment（影子模式）
|
||||
- Challenger 模型在生产流量上实时评分，但**不实际影响决策**
|
||||
- 所有输出被记录但不触发行动
|
||||
- 优势：无需 A/B 分流风险，收集真实分布数据
|
||||
|
||||
### A/B Split（分流测试）
|
||||
- 将生产流量按比例分配给 Champion 和 Challenger
|
||||
- Challenger 的预测直接触发实际决策
|
||||
- 适用场景：需要真实业务反馈且风险可控时
|
||||
|
||||
### Multi-Challenger Ranking
|
||||
- 同时存在多个 Challenger 时，按以下优先级评估：
|
||||
1. **统计显著性**：AUC/KS 提升是否有统计意义（DeLong test）
|
||||
2. **业务影响**：性能提升的绝对业务价值（Revenue/Cost/Conversion）
|
||||
3. **稳定性**：Challenger 在各子群体和时间窗口上的表现一致性
|
||||
4. **可解释性**：SHAP 特征重要性是否发生重大结构性变化
|
||||
|
||||
## Model QA 中的应用
|
||||
|
||||
Model QA Specialist 使用 Champion-Challenger 框架执行以下审计：
|
||||
1. **基准建立**：记录 Champion 模型的 AUC/Gini/KS 基准值和跨切片表现
|
||||
2. **Challenger 评估**：对候选模型进行全 10 域审计，不限于性能指标
|
||||
3. **迁移决策**：只有 Challenger 在**所有关键域**达到或超越 Champion 时才建议迁移
|
||||
4. **回滚计划**：每次 Challenger 上线必须有可执行的回滚方案
|
||||
|
||||
## Relationship
|
||||
|
||||
- **依赖** [[Discrimination-Metrics]]：AUC/Gini/KS 是量化 Champion vs Challenger 差异的核心指标
|
||||
- **依赖** [[Calibration-Testing]]：Hosmer-Lemeshow 检验确保 Challenger 在各子群体上的校准稳定性
|
||||
- **依赖** [[Population-Stability-Index]]：PSI 监控 Challenger 在生产分布上的稳定性
|
||||
- **依赖** [[SHAP]]：SHAP 对比分析 Challenger vs Champion 的特征贡献结构变化
|
||||
- **支撑** [[specialized-model-qa]]（Source）：Model QA Specialist 性能与监控步骤中的基准对比工具
|
||||
|
||||
## Key Insights
|
||||
|
||||
- **不只看 AUC**：Champion 升级决策必须综合考虑性能、公平性、校准和业务影响
|
||||
- **时间窗口**：必须收集足够长时间（至少一个业务周期）的 Challenger 数据
|
||||
- **灰度发布**：避免一次性全量切换，先小比例验证再扩大
|
||||
- **监管合规**：金融/医疗等受监管行业的模型更换须符合模型变更治理流程
|
||||
40
wiki/concepts/Chaos-Physics.md
Normal file
40
wiki/concepts/Chaos-Physics.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: "Chaos Physics"
|
||||
type: concept
|
||||
tags: ["unreal-engine", "physics", "destruction", "chaos-engine"]
|
||||
sources: ["unreal-systems-engineer"]
|
||||
last_updated: 2026-05-30
|
||||
---
|
||||
|
||||
## Aliases
|
||||
- Chaos Destruction System
|
||||
- UE5 Chaos Physics Engine
|
||||
- Geometry Collections
|
||||
|
||||
## 定义
|
||||
Chaos 是 UE5 的物理与破坏系统，提供实时网格破碎、刚体约束和高级物理模拟能力。
|
||||
|
||||
## 核心组件
|
||||
|
||||
### Geometry Collections
|
||||
- 用于实时网格破碎的破碎几何体集合
|
||||
- 在 Fracture Editor 中制作破碎资产
|
||||
- 通过 `UChaosDestructionListener` 触发破碎事件
|
||||
|
||||
### Constraint Types
|
||||
Chaos 支持多种约束类型：
|
||||
- **Rigid**（刚性）— 固定断裂块之间的连接
|
||||
- **Soft**（柔性）— 允许一定形变的连接
|
||||
- **Spring**（弹簧）— 带弹性的连接
|
||||
- **Suspension**（悬挂）— 模拟悬挂系统
|
||||
|
||||
### Destruction LOD
|
||||
- 近景：完整 Chaos 模拟
|
||||
- 远景：缓存动画播放（降低计算开销）
|
||||
|
||||
## 性能分析
|
||||
使用 **Unreal Insights** 的 Chaos 专用 trace 通道分析物理求解器性能。
|
||||
|
||||
## 相关概念
|
||||
- [[Actor Replication]] — 破碎物理的网络复制注意事项
|
||||
- [[UnrealEngine5]] — Chaos 是 UE5 的内置物理引擎
|
||||
40
wiki/concepts/CharacterArc.md
Normal file
40
wiki/concepts/CharacterArc.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: "Character Arc"
|
||||
type: concept
|
||||
tags: []
|
||||
sources: []
|
||||
last_updated: 2026-04-30
|
||||
---
|
||||
|
||||
## Aliases
|
||||
- Character Arc
|
||||
- 角色弧线
|
||||
- 角色发展弧
|
||||
|
||||
## Overview
|
||||
Character Arc（角色弧线）描述角色在叙事过程中从起始状态到终态的内在变化轨迹。与角色在情节中采取的行动（Plot Arc）不同，Character Arc 关注角色的内心世界、信念体系和心理成熟度。
|
||||
|
||||
## Arc Types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| **Transformative** | 角色核心信念被颠覆，实现内在成长或改变 |
|
||||
| **Steadfast** | 角色信念被考验但最终被确认为正确坚守 |
|
||||
| **Flat** | 角色不经历内在变化（通常是功能性角色） |
|
||||
| **Tragic** | 角色因无法克服内在缺陷或错误选择而走向毁灭 |
|
||||
| **Comedic** | 角色通过接受内在真相获得和谐/社会整合 |
|
||||
|
||||
## Core Components（[[Academic Narratologist]] 模型）
|
||||
|
||||
### Four Checkpoints
|
||||
1. **Want（欲望/外在目标）**：角色在情节中追求的具体目标
|
||||
2. **Need（需求/内在必要性）**：角色真正需要获得的东西（通常与其 Want 不同）
|
||||
3. **Lie（信念谎言）**：角色持有但需要被挑战的错误信念
|
||||
4. **Transformation（蜕变）**：角色面对真相时的内在改变
|
||||
|
||||
### Supporting Elements
|
||||
- **Ghost/Wound**：驱动角色行为的过往创伤或经历
|
||||
- **Backstory**：支撑 Ghost 的具体事件
|
||||
|
||||
## Application
|
||||
[[Academic Narratologist]] 的核心分析工具之一。每个角色弧线都必须有清晰的 want/need/lie/transformation 四个要素，并通过故事事件逐一验证。
|
||||
35
wiki/concepts/ChatCompletions.md
Normal file
35
wiki/concepts/ChatCompletions.md
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: "ChatCompletions"
|
||||
type: concept
|
||||
tags:
|
||||
- "openai"
|
||||
- "api"
|
||||
- "chat"
|
||||
sources: []
|
||||
last_updated: 2026-04-20
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Chat Completions 是 OpenAI 标准的聊天补全 API 格式，通过 `POST /v1/chat/completions` 端点调用。Hermes Agent 的 API Server 默认使用此模式，无需额外配置。
|
||||
|
||||
## Key Characteristics
|
||||
|
||||
- **请求格式**：`{"model": "...", "messages": [...]}`
|
||||
- **响应格式**：返回 `choices[].message` 完整回复
|
||||
- **历史管理**：每次请求携带完整对话历史
|
||||
- **工具调用**：支持 `tools` / `tool_calls` 参数
|
||||
- **流式输出**：支持 `stream: true`，实时推送 token
|
||||
|
||||
## vs Responses API
|
||||
|
||||
| 特性 | Chat Completions | Responses API |
|
||||
|---|---|---|
|
||||
| 状态管理 | 客户端携带历史 | 服务端 `previous_response_id` |
|
||||
| 事件流 | 逐 token 块 | 结构化事件（text_delta, function_call） |
|
||||
| 稳定性 | 稳定（默认） | 实验性 |
|
||||
| 适用场景 | 通用对话 | 需要服务端状态追踪的场景 |
|
||||
|
||||
## See Also
|
||||
- [[APIServer]]
|
||||
- [[ResponsesAPI]]
|
||||
81
wiki/concepts/Checks-Effects-Interactions.md
Normal file
81
wiki/concepts/Checks-Effects-Interactions.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
title: "Checks-Effects-Interactions Pattern"
|
||||
type: concept
|
||||
tags: [blockchain, security, smart-contract, reentrancy, best-practices]
|
||||
sources: [blockchain-security-auditor]
|
||||
last_updated: 2026-05-30
|
||||
---
|
||||
|
||||
## Aliases
|
||||
- Checks-Effects-Interactions
|
||||
- CEI Pattern
|
||||
- Checks-Effects-Interactions Pattern
|
||||
|
||||
## Definition
|
||||
|
||||
Checks-Effects-Interactions（CEI，检查-效果-交互）模式是智能合约安全编程的核心防御模式，用于防止重入攻击和其他逻辑漏洞。其核心原则是：**在执行任何外部调用之前，先完成所有的状态检查和状态更新**。
|
||||
|
||||
## Pattern
|
||||
|
||||
```
|
||||
function withdraw() external {
|
||||
// 1. CHECKS — 验证前置条件
|
||||
require(balances[msg.sender] > 0, "No balance");
|
||||
|
||||
// 2. EFFECTS — 更新合约状态（在外部调用之前）
|
||||
balances[msg.sender] = 0;
|
||||
|
||||
// 3. INTERACTIONS — 执行外部调用（最后一步）
|
||||
(bool success,) = msg.sender.call{value: amount}("");
|
||||
require(success, "Transfer failed");
|
||||
}
|
||||
```
|
||||
|
||||
## Why It Works
|
||||
|
||||
传统重入攻击利用的漏洞链：
|
||||
```
|
||||
外部调用（ETH转账）→ 攻击者receive()被触发
|
||||
→ 攻击者 re-enter withdraw()
|
||||
→ balances[msg.sender] 仍 > 0（未清零）
|
||||
→ 重复提取资金
|
||||
```
|
||||
|
||||
CEI 模式切断漏洞链：**状态在外部调用之前清零**，即使攻击者 re-enter，条件检查阶段 `require(balances[msg.sender] > 0)` 已失败。
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### Wrong Order (Vulnerable)
|
||||
```solidity
|
||||
// VULNERABLE: 外部调用在状态更新之前
|
||||
(bool success,) = msg.sender.call{value: amount}("");
|
||||
require(success);
|
||||
balances[msg.sender] = 0; // 攻击者可在此之前 re-enter
|
||||
```
|
||||
|
||||
### Missing Update (Vulnerable)
|
||||
```solidity
|
||||
// VULNERABLE: 状态根本没有更新
|
||||
require(balances[msg.sender] > 0);
|
||||
(bool success,) = msg.sender.call{value: amount}("");
|
||||
require(success);
|
||||
// balances[msg.sender] = 0; ← 忘记更新！
|
||||
```
|
||||
|
||||
### ERC-20 Transfer Before Update
|
||||
```solidity
|
||||
// VULNERABLE: ERC-20 transfer 触发外部调用
|
||||
IERC20(token).transfer(msg.sender, amount); // 外部调用
|
||||
balances[msg.sender] -= amount; // 状态更新太晚
|
||||
```
|
||||
|
||||
## Relationship to Other Defenses
|
||||
|
||||
- **CEI is the primary defense** — should always be applied first
|
||||
- **ReentrancyGuard is additional defense** — use when CEI is difficult to apply (complex logic, callbacks)
|
||||
- CEI + ReentrancyGuard together provide defense in depth
|
||||
|
||||
## Connections
|
||||
- [[Reentrancy]] ← prevents ← [[Checks-Effects-Interactions]]
|
||||
- [[Blockchain-Security-Auditor]] ← enforces ← [[Checks-Effects-Interactions]]
|
||||
- [[ReentrancyGuard]] ← supplements ← [[Checks-Effects-Interactions]]
|
||||
41
wiki/concepts/ChecksEffectsInteractions.md
Normal file
41
wiki/concepts/ChecksEffectsInteractions.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: "ChecksEffectsInteractions"
|
||||
type: concept
|
||||
tags: []
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Definition
|
||||
_checks-effects-interactions_ 是 Solidity 智能合约开发的核心安全原则，规定函数内操作必须按以下顺序执行：
|
||||
|
||||
1. **Checks**：验证前置条件（require/assert 语句）
|
||||
2. **Effects**：更新合约内部状态（状态变量修改）
|
||||
3. **Interactions**：执行外部调用（token transfer、合约调用等）
|
||||
|
||||
## Why It Matters
|
||||
违反此顺序会导致 **重入攻击（Reentrancy Attack）**。如果外部调用在状态更新之前执行，攻击者的恶意合约可以在状态仍然显示"资金未提取"的情况下递归调用 withdraw()，反复提取资金。
|
||||
|
||||
### Vulnerable Pattern (违反 CEI)
|
||||
```solidity
|
||||
function withdraw(uint256 amount) external {
|
||||
require(balances[msg.sender] >= amount);
|
||||
// ❌ 外部调用在状态更新之前
|
||||
msg.sender.call{value: amount}("");
|
||||
balances[msg.sender] -= amount; // 太晚了
|
||||
}
|
||||
```
|
||||
|
||||
### Secure Pattern (遵循 CEI)
|
||||
```solidity
|
||||
function withdraw(uint256 amount) external {
|
||||
require(balances[msg.sender] >= amount);
|
||||
balances[msg.sender] -= amount; // ✅ 先更新状态
|
||||
emit Withdrawal(msg.sender, amount);
|
||||
msg.sender.call{value: amount}(""); // ✅ 最后外部调用
|
||||
}
|
||||
```
|
||||
|
||||
## Sources
|
||||
- [[engineering-solidity-smart-contract-engineer]]
|
||||
- [[The-DAO]]
|
||||
- [[blockchain-security-auditor]]
|
||||
40
wiki/concepts/Circuit-Breaker.md
Normal file
40
wiki/concepts/Circuit-Breaker.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: "Circuit Breaker"
|
||||
type: concept
|
||||
tags: []
|
||||
sources: [engineering-autonomous-optimization-architect]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
# Circuit Breaker
|
||||
|
||||
## Definition
|
||||
|
||||
熔断器模式（Circuit Breaker）——当某个 LLM API 端点连续失败超过预设阈值时，自动切断对该端点的路由，将流量切换到降级路径，同时向人工告警。
|
||||
|
||||
## Mechanism
|
||||
|
||||
1. **Closed（正常）**：所有请求正常路由到目标端点
|
||||
2. **Open（熔断）**：端点连续失败超过阈值，立即切断路由，所有请求跳过该端点
|
||||
3. **Half-Open（半开）**：经过冷却期后，放行少量请求试探端点是否恢复
|
||||
|
||||
## Trigger Conditions
|
||||
|
||||
- 端点流量异常激增（500%+，可能为恶意 bot 攻击）
|
||||
- 连续出现 HTTP 402（需要付费）/ 429（速率限制）错误
|
||||
- 单次请求成本超过安全上限（如 $0.05/次）
|
||||
|
||||
## Example
|
||||
|
||||
```typescript
|
||||
if (provider.failures > securityLimits.maxRetries) {
|
||||
tripCircuitBreaker(provider);
|
||||
routeToFallback(provider);
|
||||
alertAdmin(`Circuit breaker tripped: ${provider.name}`);
|
||||
}
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
- [[Autonomous-Optimization-Architect]]：使用熔断器保护 AI 路由系统的核心组件
|
||||
- [[AI-FinOps]]：熔断器是 FinOps 成本控制的最后防线
|
||||
36
wiki/concepts/CodebaseOnboarding.md
Normal file
36
wiki/concepts/CodebaseOnboarding.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: "CodebaseOnboarding"
|
||||
type: concept
|
||||
tags: []
|
||||
last_updated: 2026-05-02
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Codebase Onboarding 是帮助新开发者快速理解陌生代码库的方法论和实践体系。核心目标是缩短从"首次接触代码库"到"能够独立定位问题、修改代码"的认知建立时间。
|
||||
|
||||
## Core Principles
|
||||
|
||||
- **Evidence-first**: 只陈述代码中可验证的事实
|
||||
- **Layered explanation**: 分层递进式解释（一句话 → 五分钟 → 深度代码流）
|
||||
- **File-level precision**: 所有结论必须指向具体文件路径
|
||||
- **Honest scope**: 明确告知哪些部分已检查、哪些未检查
|
||||
|
||||
## Key Methods
|
||||
|
||||
1. **Inventory & Classification** — 识别清单文件（manifests/lockfiles）、框架标记、构建工具、顶层目录
|
||||
2. **Entry Point Discovery** — 找到启动文件、路由、处理器、CLI 命令
|
||||
3. **Execution Tracing** — 端到端追踪输入→验证→编排→持久化→输出
|
||||
4. **Boundary Analysis** — 识别模块边界、包边界、共享工具、重复职责
|
||||
|
||||
## Usage Context
|
||||
|
||||
- 新开发者 onboarding
|
||||
- 大型代码库结构探索
|
||||
- 故障定位前的代码结构理解
|
||||
|
||||
## Related Concepts
|
||||
|
||||
- [[ExecutionTracing]] — 执行路径追踪
|
||||
- [[EvidenceFirstReasoning]] — 证据优先推理
|
||||
- [[MinimalChangePrinciple]] — 与 [[EngineeringMinimalChangeEngineer]] 配合使用
|
||||
@@ -1,29 +1,46 @@
|
||||
---
|
||||
title: "Cognitive Load Reduction"
|
||||
type: concept
|
||||
tags: [ux, productivity, behavioral-psychology, task-management]
|
||||
last_updated: 2026-04-20
|
||||
---
|
||||
|
||||
## Definition
|
||||
认知负荷降低（Cognitive Load Reduction）指通过界面设计、任务拆分和流程优化，减少用户完成任务所需的心理努力，防止决策疲劳和任务瘫痪。
|
||||
|
||||
## Mechanism
|
||||
1. **任务拆分**：将大型工作流分解为微小、可完成的微任务单元
|
||||
2. **单一焦点**：每次仅推送一个最高优先级的可操作项，而非批量列表
|
||||
3. **渐进披露**：按需逐步展示信息，避免信息过载
|
||||
4. **即时上下文**：为每个任务提供充分的执行背景，减少搜索和回忆成本
|
||||
|
||||
## Applications
|
||||
- 微冲刺（Micro-Sprint）：5-15 分钟短时任务块
|
||||
- [[Pomodoro Technique]] 时间盒工作
|
||||
- 队列视图仅显示当前最关键项
|
||||
- ADHD 用户友好设计模式
|
||||
|
||||
## Related Concepts
|
||||
- [[Default Bias]]：降低决策摩擦的互补机制
|
||||
- [[Pomodoro Technique]]：时间盒化的认知负荷管理实践
|
||||
- [[Momentum Nudge]]：维持用户行动动量防止认知疲劳
|
||||
|
||||
## Source
|
||||
- [[Behavioral Nudge Engine]] — 核心应用场景
|
||||
---
|
||||
title: "Cognitive Load Reduction"
|
||||
type: concept
|
||||
tags: []
|
||||
sources: ["product-behavioral-nudge-engine"]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Cognitive Load Reduction（认知负荷降低）是一种软件交互设计原则——通过信息过滤、任务分解和界面简化，主动降低用户在决策和执行过程中的认知负担，防止因信息过载导致的决策瘫痪和平台流失。
|
||||
|
||||
## Core Problem
|
||||
|
||||
> "If a user has 50 items pending, do not show them 50. Show them the 1 most critical item."
|
||||
|
||||
大量待办任务列表是认知过载的典型来源。当用户面对大量未完成任务时，会产生「决策瘫痪」——因无法决定从何处开始而选择什么都不做。
|
||||
|
||||
## Strategy Taxonomy
|
||||
|
||||
| 策略 | 描述 | 示例 |
|
||||
|------|------|------|
|
||||
| 信息过滤 | 只展示最关键的N项 | 任务列表只显示 Top 1 |
|
||||
| 任务分解 | 将复杂任务拆解为微步骤 | 将「完成项目报告」拆解为「只写第一段」 |
|
||||
| 预设草案 | 预先填充内容减少起步阻力 | [[Default Bias]] 的应用 |
|
||||
| 时间盒 | 限制单次执行时长 | [[Micro-Sprint]] 5分钟冲刺 |
|
||||
| 进度可见 | 展示已完成vs总任务数 | 庆祝15个已完成而非展示95个待完成 |
|
||||
|
||||
## Behavioral Science Foundation
|
||||
|
||||
- **Miller's Law**：人类工作记忆容量约为 7±2 个信息块
|
||||
- **Zeigarnik Effect**：未完成任务比已完成任务占用更多认知资源
|
||||
- **Goal Gradient Effect**：越接近目标，动机越强——通过展示小范围完成积累信心
|
||||
|
||||
## Related Concepts
|
||||
|
||||
- [[Micro-Sprint]] — 认知负荷降低的核心执行机制
|
||||
- [[Default Bias]] — 通过预设草案降低决策门槛
|
||||
- [[Gamification]] — 通过进度可视化维持动力
|
||||
- [[Habit Formation]] — 低认知负荷是习惯形成的前提条件
|
||||
|
||||
## Connections
|
||||
|
||||
- [[Behavioral Nudge Engine]] — 认知负荷管理是核心职责
|
||||
- [[Product Manager Agent]] — 产品设计需内化认知负荷原则
|
||||
- [[Habit Tracker & Accountability Coach]] — 低摩擦的habit建立依赖认知负荷控制
|
||||
|
||||
61
wiki/concepts/Command-Theater.md
Normal file
61
wiki/concepts/Command-Theater.md
Normal file
@@ -0,0 +1,61 @@
|
||||
---
|
||||
title: "Command Theater"
|
||||
type: concept
|
||||
tags: []
|
||||
last_updated: 2026-03-05
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Command Theater（指挥剧场）是 [[nexus-spatial-discovery]] 中 [[Nexus Spatial]] 产品定义的空间界面布局架构——以用户为中心的弧形"指挥剧场"，将工作空间按功能分层布局于不同深度和角度。
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
OVERVIEW CANOPY
|
||||
(pipeline topology)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
/ \
|
||||
/ FOCUS ARC (120 deg) \
|
||||
/ primary node graph work \
|
||||
/________________________________\
|
||||
| |
|
||||
LEFT | USER POSITION | RIGHT
|
||||
UTILITY | (origin 0,0,0) | UTILITY
|
||||
RAIL | | RAIL
|
||||
|__________________________________|
|
||||
\ /
|
||||
\ SHELF (below sightline) /
|
||||
\ agent status, quick tools/
|
||||
\_________________________ /
|
||||
```
|
||||
|
||||
## Four Zones
|
||||
|
||||
| 区域 | 深度范围 | 内容 | 透明度 |
|
||||
|------|---------|------|--------|
|
||||
| **Overview Canopy**（天幕） | 2.5–4.0m | 管线拓扑 + 健康热力图 | 40–70% |
|
||||
| **Focus Arc**（聚焦弧） | 1.2–2.0m | 主节点图工作区 | 100% |
|
||||
| **Utility Rails**（工具轨） | 侧翼 | Agent 库、监控、日志 | 100% |
|
||||
| **Shelf**（置物架） | 0.8–1.0m | 运行/停止、撤销、快捷工具 | 100% |
|
||||
|
||||
## Three-Layer Depth System
|
||||
|
||||
| 层级 | 深度 | 内容 | 透明度 |
|
||||
|------|------|------|--------|
|
||||
| Foreground（前景） | 0.8–1.2m | 活跃面板、检测器、模态框 | 100% |
|
||||
| Midground（中景） | 1.2–2.5m | 节点图、连接线、工作区 | 100% |
|
||||
| Background（背景） | 2.5–5.0m | 概览地图、环境状态 | 40–70% |
|
||||
|
||||
## Design Rationale
|
||||
|
||||
- **120 度聚焦弧**覆盖人眼自然视野中心区域
|
||||
- **垂直分层**（天幕→聚焦→置物架）符合"最重要信息在视线中心，次要在下方"的直觉
|
||||
- **侧翼工具轨**让主工作区保持无遮挡
|
||||
- **深度层级**允许信息密度分层——背景展示概览，前景展示细节
|
||||
|
||||
## Connections
|
||||
|
||||
- [[SpatialAIOps]] ← 界面架构层
|
||||
- [[Command-Theater]] ← 自身引用
|
||||
- [[4-Level-Semantic-Zoom]] ← 导航模式
|
||||
66
wiki/concepts/Concierge-Services.md
Normal file
66
wiki/concepts/Concierge-Services.md
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: "Concierge Services"
|
||||
type: concept
|
||||
tags: []
|
||||
sources:
|
||||
- hospitality-guest-services
|
||||
last_updated: 2026-05-02
|
||||
---
|
||||
|
||||
## Definition
|
||||
Concierge Services（礼宾服务）是酒店及高端款待业中，为宾客提供本地知识、预订协调和个性化安排的专业服务职能。礼宾服务的核心价值在于：识别宾客未表达的需求，通过主动推荐和精准执行创造惊喜体验。
|
||||
|
||||
## Service Categories
|
||||
|
||||
### Dining Reservations（餐饮预订）
|
||||
- 掌握当地TOP 10餐厅分类（Fine Dining/Casual/家庭/本地人推荐/景观氛围）
|
||||
- 实时了解：当前等候时间、预订可用性、饮食适配能力
|
||||
- 预订话术："请问您偏好什么菜系、价格范围和氛围？有什么特殊场合需要我们提及吗？"
|
||||
- 交通选项：每家餐厅的交通方式建议
|
||||
|
||||
### Transportation（交通安排）
|
||||
- 酒店班车：时刻表和覆盖范围
|
||||
- 打车/网约车：本地最佳APP
|
||||
- 租车：最近门店位置和当前可用车型
|
||||
- 停车：自助vs.代客泊车，费用，营业时间
|
||||
- 机场接送：预订流程和价格
|
||||
|
||||
### Local Activities & Attractions（本地活动与景点）
|
||||
保持实时更新的知识库：
|
||||
- 主要景点：开放时间、票价、预订要求
|
||||
- 当前本地活动：节日、音乐会、体育赛事
|
||||
- 户外活动：徒步、公园、水上活动
|
||||
- 家庭友好选项
|
||||
- 文化体验：博物馆、剧院、画廊
|
||||
- 购物：本地精品店、商场、市场
|
||||
|
||||
### In-Property Services（酒店内服务）
|
||||
- Spa：护理项目、营业时间、预订流程
|
||||
- 健身中心：开放时间、设备、课程
|
||||
- 泳池：开放时间、规则、毛巾服务
|
||||
- 商务中心：开放时间、设备、打印
|
||||
- 客房服务：开放时间、点餐流程
|
||||
- 洗衣/干洗：流程和 turnaround 时间
|
||||
|
||||
### Special Occasion Services（特殊场合服务）
|
||||
- 鲜花：通过[供应商]订购，需24小时通知
|
||||
- 香槟/葡萄酒：通过客房服务供应
|
||||
- 蛋糕：通过[供应商]订购，需24小时通知
|
||||
- 浪漫夜床布置：玫瑰+蜡烛，需[时间]前申请
|
||||
- 惊喜布置：与客房部协调
|
||||
|
||||
## Key Principles
|
||||
- 主动推荐，而非被动应答：识别宾客需求在开口前
|
||||
- 知识必须实时更新：餐厅关门时间、景点开放日变化
|
||||
- 饮食限制是医疗问题：每次餐饮预订必须记录
|
||||
|
||||
## Connections
|
||||
- [[Hospitality Guest Services]] ← 礼宾服务是宾客服务 Agent 住店阶段的核心交付物
|
||||
- [[Guest Journey]] ← 礼宾服务贯穿住店(In-Stay)阶段
|
||||
- [[Food Allergy]] ← 礼宾服务中餐饮预订必须强制处理饮食限制
|
||||
|
||||
## Aliases
|
||||
- 礼宾服务
|
||||
- Concierge
|
||||
- Guest Services
|
||||
- Hotel Concierge
|
||||
46
wiki/concepts/ConnectionPooling.md
Normal file
46
wiki/concepts/ConnectionPooling.md
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: "Connection Pooling"
|
||||
type: concept
|
||||
tags: [database, connection-pool, postgresql, supabase, performance, infrastructure]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
# Connection Pooling
|
||||
|
||||
## Definition
|
||||
|
||||
数据库连接池是一种在应用程序和数据库服务器之间维护一组持久连接的技术，避免每次请求都创建新连接，从而防止连接耗尽、提升响应速度。
|
||||
|
||||
## Why It Matters
|
||||
|
||||
- 数据库连接是稀缺资源（PostgreSQL 默认 max_connections = 100）
|
||||
- 无连接池时：高并发下连接数爆炸 → OOM → 服务崩溃
|
||||
- 无连接池时：每次请求建立 TCP + 认证开销（~20-50ms 延迟）
|
||||
|
||||
## Key Tools
|
||||
|
||||
| 工具 | 说明 |
|
||||
|------|------|
|
||||
| **PgBouncer** | 轻量级 PostgreSQL 连接池，支持事务模式和会话模式 |
|
||||
| **Supabase Pooler** | Supabase 内置连接池，自动管理事务模式连接 |
|
||||
| **PlanetScale** | 内置连接池，无服务器架构 |
|
||||
| **PgBouncer 事务模式** | 连接归还池复用，适合 serverless |
|
||||
| **PgBouncer 会话模式** | 保持长连接，适合需要 SET session.* 的场景 |
|
||||
|
||||
## Supabase 连接池示例
|
||||
|
||||
```typescript
|
||||
// Supabase 事务模式（Serverless 推荐）
|
||||
const pooledUrl = process.env.DATABASE_URL?.replace(
|
||||
'5432', // 标准端口
|
||||
'6543' // 事务模式端口
|
||||
);
|
||||
```
|
||||
|
||||
## Source
|
||||
- [[engineering-database-optimizer]]
|
||||
|
||||
## Connections
|
||||
- [[engineering-backend-architect]] — 架构设计时必须考虑连接池
|
||||
- [[engineering-sre]] — 连接池配置是 SRE 容量规划的关键
|
||||
- [[engineering-database-optimizer]] — 核心关注点之一
|
||||
48
wiki/concepts/Content-Operations.md
Normal file
48
wiki/concepts/Content-Operations.md
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: "内容运营体系（Content Operations for Proposals）"
|
||||
type: concept
|
||||
tags: [sales, content, operations]
|
||||
sources: [sales-proposal-strategist]
|
||||
last_updated: 2026-04-29
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
内容运营体系（Content Operations）是提案内容资产的管理方法论，核心变革是：**按赢主题（而非按提案章节）组织可复用内容库**，从而加速未来提案撰写并保持叙事一致性。
|
||||
|
||||
## 核心原则
|
||||
|
||||
1. **按主题组织**：每个内容块归属于一个或多个赢主题，而非某个提案章节
|
||||
2. **主题覆盖率追踪**：每个提案章节必须有 ≥1 个赢主题覆盖
|
||||
3. **证据密度要求**：每个内容块必须有可引用证据（指标/案例/方法论细节）
|
||||
|
||||
## 收益
|
||||
|
||||
| 传统方式 | 内容运营方式 |
|
||||
|----------|--------------|
|
||||
| 每份提案从零写 | 调用主题库中已有内容 |
|
||||
| 主题在不同章节中自相矛盾 | 主题由中心库驱动，一致性强 |
|
||||
| 模板化内容难以消除 | 内容按主题标记，可识别并替换通用内容 |
|
||||
| 经验随人员流失 | 知识沉淀在主题库中 |
|
||||
|
||||
## 模板检测与消除
|
||||
|
||||
识别模板化内容的信号：
|
||||
- 将买家名称替换后内容完全不变
|
||||
- "Robust," "cutting-edge," "best-in-class," "world-class" 等空洞形容词
|
||||
- 任何可以直接卖给竞争对手的内容
|
||||
|
||||
## 与赢主题的关系
|
||||
|
||||
内容运营体系是赢主题的后勤保障：
|
||||
- 赢主题定义"说什么"
|
||||
- 内容运营定义"如何组织、存储和复用"
|
||||
|
||||
## Related Concepts
|
||||
|
||||
- [[Win Theme]]：内容运营体系的核心组织轴
|
||||
- [[三幕式提案叙事]]：内容在叙事中的布局框架
|
||||
|
||||
## Sources
|
||||
|
||||
- [[sales-proposal-strategist]]
|
||||
47
wiki/concepts/Context-Anxiety.md
Normal file
47
wiki/concepts/Context-Anxiety.md
Normal file
@@ -0,0 +1,47 @@
|
||||
---
|
||||
title: "Context Anxiety"
|
||||
type: concept
|
||||
tags:
|
||||
- "agentic-ai"
|
||||
- "context-window"
|
||||
- "failure-mode"
|
||||
sources:
|
||||
- "Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog"
|
||||
last_updated: 2026-04-20
|
||||
---
|
||||
|
||||
## Overview
|
||||
Context Anxiety——当 LLM 的 context window 使用率超过约 70% 容量，或延迟升高时，模型表现出"仓促"行为的现象：跳过步骤、过早完成任务或过早宣告成功。
|
||||
|
||||
## Mechanism
|
||||
- Context window 是模型的唯一记忆空间
|
||||
- 当感知到"墙壁在逼近"（token 限制），模型开始优先"快速完成"而非"正确完成"
|
||||
- 这不是模型能力问题，而是 context 容量压力的系统性反应
|
||||
|
||||
## Detection
|
||||
- 监控 `tokens_used / max_context > 0.7` 阈值（需按模型和工作负载调优）
|
||||
- 延迟 spikes 也是触发信号
|
||||
|
||||
## Solution: Context Reset
|
||||
当 Context Anxiety 触发时，Harness 执行程序化 Context Reset：
|
||||
1. `save_state_to_disk(state)` — 完整项目状态写入持久存储
|
||||
2. `terminate_current_instance()` — 终止当前 LLM 实例
|
||||
3. `launch_fresh_agent(state)` — 启动全新 Agent，从保存状态恢复
|
||||
|
||||
关键代码：
|
||||
```python
|
||||
if (tokens_used / max_context) > 0.7:
|
||||
save_state_to_disk(state)
|
||||
terminate_current_instance()
|
||||
launch_fresh_agent(state)
|
||||
```
|
||||
|
||||
## Note on In-Place Summarization
|
||||
原地摘要（in-place summarization）不够——它仍然让模型在杂乱、退化的 context 上操作。Context Reset 给予模型干净的处理空间。
|
||||
|
||||
## Source
|
||||
- [[Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog]]
|
||||
|
||||
## See Also
|
||||
- [[Context-Reset]] — 具体实现机制
|
||||
- [[7-Layer-Harness-Stack]] — 第 5 层 Memory & State 和第 7 层 Constraints & Recovery 中处理此问题
|
||||
41
wiki/concepts/Context-Reset.md
Normal file
41
wiki/concepts/Context-Reset.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: "Context Reset"
|
||||
type: concept
|
||||
tags:
|
||||
- "agentic-ai"
|
||||
- "context-window"
|
||||
- "recovery"
|
||||
sources:
|
||||
- "Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog"
|
||||
last_updated: 2026-04-20
|
||||
---
|
||||
|
||||
## Overview
|
||||
Context Reset——当 [[Context-Anxiety]] 触发时，Harness 将当前 Agent 状态保存至磁盘、终止实例、启动全新 Agent 的程序化操作，用于解决长周期任务超出单次 context window 的问题。
|
||||
|
||||
## Trigger Condition
|
||||
```python
|
||||
if (tokens_used / max_context) > 0.7: # 阈值需按模型调优
|
||||
trigger_context_reset()
|
||||
```
|
||||
|
||||
## Procedure
|
||||
1. **Save state**: 完整项目状态写入持久存储（磁盘文件）
|
||||
2. **Terminate**: 终止当前 LLM 实例
|
||||
3. **Launch fresh**: 启动全新 Agent，加载保存状态
|
||||
4. **Orient**: 新 Agent 读取状态、定位自身、继续工作
|
||||
|
||||
## Why Not In-Place Summarization?
|
||||
原地摘要（summarize → keep in same context）仍让模型在嘈杂、退化的上下文中操作。Context Reset 提供完全干净的上下文窗口——代价更高，但可靠性显著提升，适用于超长周期任务。
|
||||
|
||||
## Trade-off
|
||||
- **In-place summarization**: 便宜，但 context 仍嘈杂
|
||||
- **Context Reset**: 昂贵（需重新加载状态），但可靠性高
|
||||
|
||||
## Source
|
||||
- [[Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog]]
|
||||
|
||||
## See Also
|
||||
- [[Context-Anxiety]] — 触发条件
|
||||
- [[State-Externalization]] — 持久化状态文件格式
|
||||
- [[7-Layer-Harness-Stack]] — 第 7 层 Constraints & Recovery 的核心机制
|
||||
32
wiki/concepts/Continuous-Dev-QA-Loop.md
Normal file
32
wiki/concepts/Continuous-Dev-QA-Loop.md
Normal file
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: "Continuous-Dev-QA-Loop"
|
||||
type: concept
|
||||
tags: []
|
||||
sources: [agents-orchestrator]
|
||||
last_updated: 2026-05-29
|
||||
---
|
||||
|
||||
## Definition
|
||||
**Continuous Dev-QA Loop**（持续开发质量循环）是 [[AgentsOrchestrator]] Phase 3 的核心机制——开发与 QA 交替进行，每个开发交付物立即经过 QA 验证，形成快速反馈闭环。
|
||||
|
||||
## Relationship to [[Dev-QA-Loop]]
|
||||
- [[Dev-QA-Loop]] is the specific implementation of this concept within the AgentsOrchestrator pipeline
|
||||
- Continuous Dev-QA Loop is the broader principle: rapid feedback between development and quality assurance
|
||||
|
||||
## Core Principle
|
||||
> "No shortcuts: Every task must pass QA validation."
|
||||
|
||||
## Loop Characteristics
|
||||
- **Continuous**: No waiting until end-of-project QA — validation happens after each task
|
||||
- **Fast feedback**: Developer receives specific feedback immediately after implementation
|
||||
- **Evidence-based**: QA requires visual/screenshot proof, not self-reported completion
|
||||
- **Iterative**: Loop continues until PASS or max retries reached
|
||||
|
||||
## Benefits
|
||||
- Issues caught early before propagating to downstream tasks
|
||||
- Developer receives specific, actionable feedback
|
||||
- Quality gates prevent broken functionality from advancing
|
||||
- Reduced final integration issues due to continuous validation
|
||||
|
||||
## Sources
|
||||
- [[agents-orchestrator]]
|
||||
36
wiki/concepts/ControllingIdea.md
Normal file
36
wiki/concepts/ControllingIdea.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: "Controlling Idea"
|
||||
type: concept
|
||||
tags: []
|
||||
sources: []
|
||||
last_updated: 2026-04-30
|
||||
---
|
||||
|
||||
## Aliases
|
||||
- Controlling Idea
|
||||
- 核心主题
|
||||
- 主题性论点
|
||||
|
||||
## Overview
|
||||
Controlling Idea 是 [[Robert McKee]] 在其著作《故事》中提出的核心概念，定义为"故事对人性的论点"——它通过叙事中所有选择（情节、角色、场景、语言）来传达作者对人类经验的理解。
|
||||
|
||||
## Structure
|
||||
Controlling Idea = **主题性价值（Thematic Value）** × **因果关系（Causal Connection）**
|
||||
|
||||
### Examples
|
||||
| Controlling Idea | Thematic Value | Causal Connection |
|
||||
|-----------------|---------------|-------------------|
|
||||
| "骄傲导致毁灭" | 骄傲 | 导致 |
|
||||
| "勇气可以通过小事培养" | 勇气 | 通过...培养 |
|
||||
| "真正的力量来自放下控制" | 力量 | 通过放下获得 |
|
||||
|
||||
## Application
|
||||
[[Academic Narratologist]] 的核心分析维度之一：
|
||||
- **诊断工具**：识别故事"真正在说什么"，而非表面情节
|
||||
- **评估标准**：所有情节选择是否与 Controlling Idea 一致
|
||||
- **主题一致性检查**：跨多条情节线验证主题表达是否连贯
|
||||
|
||||
## Relationship to Other Concepts
|
||||
- [[Fabula-vs-Sjuzhet]]：Controlling Idea 是 sjuzhet（讲述层）背后的 fabula（故事层）意义
|
||||
- [[Character-Arc]]：角色的 transformation 必须与 Controlling Idea 一致
|
||||
- [[Three-Act-Structure]]：Act III 的 Resolution 必须完成主题性论点的建构
|
||||
27
wiki/concepts/Conversation-State-Persistence.md
Normal file
27
wiki/concepts/Conversation-State-Persistence.md
Normal file
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: "Conversation-State-Persistence"
|
||||
type: concept
|
||||
tags: []
|
||||
sources: [expose-hermes-agent-as-an-openai-compatible-api-for-any-frontend]
|
||||
last_updated: 2026-05-02
|
||||
---
|
||||
|
||||
## Definition
|
||||
Conversation State Persistence 是服务端存储完整对话历史（含工具调用）的机制，使客户端无需自行管理上下文。
|
||||
|
||||
## Implementation in Hermes Agent
|
||||
通过 `/v1/responses` API 实现有状态会话：
|
||||
- **无状态**：`/v1/chat/completions` 每次请求需传递完整对话历史
|
||||
- **有状态**：`/v1/responses` 支持 `previous_response_id` 链式调用，服务端保留完整上下文（含工具调用）
|
||||
|
||||
## Key Benefits
|
||||
- 客户端无需存储和发送完整对话历史
|
||||
- 服务端自动维护工具调用记录
|
||||
- 支持多轮对话中的上下文连续性
|
||||
|
||||
## Use Case
|
||||
长对话场景下，使用 Responses API 可以大幅减少客户端代码复杂度。
|
||||
|
||||
## Related
|
||||
- [[ResponsesAPI]]
|
||||
- [[System-Prompt-Layering]]
|
||||
45
wiki/concepts/Cost-As-Distributed-Systems-Bug.md
Normal file
45
wiki/concepts/Cost-As-Distributed-Systems-Bug.md
Normal file
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: "Cost As Distributed Systems Bug"
|
||||
type: concept
|
||||
tags: [sre, finops, observability, reliability, cost-optimization]
|
||||
last_updated: 2026-04-20
|
||||
---
|
||||
|
||||
# Cost As Distributed Systems Bug
|
||||
|
||||
"成本是分布式系统的 bug"——成本异常（cost explosion）不仅是财务问题，更是一种可靠性问题。
|
||||
|
||||
## Core Thesis
|
||||
成本突然增加往往预示着系统即将发生故障。**成本突增应该被视为告警信号**，触发故障调查而非仅财务审查。
|
||||
|
||||
## Why Cost Signals Matter
|
||||
1. **资源泄漏的指示器**：内存泄漏、连接池耗尽往往表现为成本逐步上升
|
||||
2. **异常流量的标志**：DDoS 或滥用可能导致成本爆炸
|
||||
3. **配置错误**：错误的资源配置可能导致资源过度使用
|
||||
4. **级联效应的前兆**：某个组件故障可能导致其他组件超负荷运转
|
||||
|
||||
## Alerting Strategy
|
||||
```
|
||||
IF cost_increase > threshold:
|
||||
ALERT("Cost anomaly detected - investigate system health")
|
||||
```
|
||||
|
||||
将成本监控集成到 SRE 的告警体系中，而非仅作为 FinOps 的事后分析。
|
||||
|
||||
## Key Principles
|
||||
- **Cost as Signal**：将成本指标视为系统健康的信号
|
||||
- **Proactive Monitoring**：在成本失控前设置告警
|
||||
- **Correlation Analysis**：将成本变化与其他系统指标关联
|
||||
|
||||
## Relationship to FinOps
|
||||
FinOps 不仅是成本优化工具，也是 SRE 的可靠性工具。成本可观测性（Cost Observability）是现代 SRE 实践的重要组成部分。
|
||||
|
||||
## Related Concepts
|
||||
- [[Cost-Optimization]]
|
||||
- [[Observability]]
|
||||
- [[FinOps]]
|
||||
- [[Distributed-Systems]]
|
||||
- [[Reliability]]
|
||||
|
||||
## Source
|
||||
- SRE Weekly Issue #513 — [[sre-weekly-issue-513]]
|
||||
34
wiki/concepts/Counterfactual-Analysis.md
Normal file
34
wiki/concepts/Counterfactual-Analysis.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: "Counterfactual Analysis"
|
||||
type: concept
|
||||
tags: [historiography, methodology]
|
||||
sources: [academic-historian]
|
||||
last_updated: 2026-04-30
|
||||
---
|
||||
|
||||
## Definition
|
||||
反事实推理（Counterfactual Analysis）是一种严谨的"假如"（what if）历史推演方法——设想历史在某个关键节点发生了不同的走向，并分析这种改变会导致什么样的后果。它是 Historian Agent 文档中明确列出的高级能力之一。
|
||||
|
||||
## Key Features
|
||||
- **核心原则**：必须以历史偶然性理论（contingency theory）为基础，而非随意想象
|
||||
- **必须满足的条件**：
|
||||
1. 反事实假设必须是"可想象的"（plausible）——基于已知历史条件
|
||||
2. 必须追溯反事实链条的逻辑后果
|
||||
3. 必须与相似历史案例进行类比验证
|
||||
4. 必须诚实地承认推理的局限性
|
||||
- **代表学者**：内弗·弗格森（Niall Ferguson）、贾雷德·戴蒙德（Jared Diamond）《枪炮、病菌与钢铁》
|
||||
- **批评**：批评者认为反事实推理过于投机，无法证伪
|
||||
- **价值**：帮助理解历史的结构性约束与偶然性因素各自的权重
|
||||
|
||||
## Relationship to Other Concepts
|
||||
- [[Longue-Duree]] ← 互补 ← [[Counterfactual-Analysis]]：长时段分析强调结构，反事实分析强调偶然性；两者共同帮助理解历史因果
|
||||
- [[Historiography]] ← 属于 ← [[Counterfactual-Analysis]]：反事实推理是历史编纂学中一种有争议但有价值的方法
|
||||
- [[academic-historian]] ← 高级能力 ← [[Counterfactual-Analysis]]：Historian Agent 的 Advanced Capabilities 明确包括 Counterfactual Analysis
|
||||
|
||||
## Relationship to Source Pages
|
||||
- [[academic-historian]]：文档的"🚀 Advanced Capabilities"部分明确列出此能力
|
||||
|
||||
## Aliases
|
||||
- 反事实推理
|
||||
- What-if Analysis
|
||||
- Alternative History
|
||||
66
wiki/concepts/CrossPlatformPlanning.md
Normal file
66
wiki/concepts/CrossPlatformPlanning.md
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: "Cross-Platform Planning"
|
||||
type: concept
|
||||
tags: ["ppc", "multi-platform", "strategy", "google-ads", "amazon-ads", "paid-media"]
|
||||
sources: ["paid-media-ppc-strategist"]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
跨平台规划（Cross-Platform Planning）是付费媒体策略中在 Google Ads、Microsoft Advertising、Amazon Ads 等多个广告平台之间协调预算分配、策略制定和效果衡量的系统性方法。核心理念：**避免平台间预算相互蚕食（cannibalization）**，通过统一的测量框架实现整体效率最优。
|
||||
|
||||
## Three Major Platforms Compared
|
||||
|
||||
| 维度 | Google Ads | Microsoft Advertising | Amazon Ads |
|
||||
|------|-----------|----------------------|-----------|
|
||||
| **用户意图** | 信息获取 → 购买 | 信息获取 → 购买（B2B更强） | 购买意图最强 |
|
||||
| **广告类型** | Search/Shop/PMax/Display/Video | Search/Shop/Audience | SP/SB/SD/DSP |
|
||||
| **量级** | 最大 | 较小但增长 | 电商专属 |
|
||||
| **CPC 水平** | 中高 | 较低 | 中等 |
|
||||
| **竞争密度** | 高 | 中低 | 中 |
|
||||
| **数据透明度** | 高 | 中 | 中 |
|
||||
|
||||
## Budget Split Frameworks
|
||||
|
||||
### Intent-Based Allocation
|
||||
```
|
||||
基于用户意图漏斗分配：
|
||||
- 品牌词：Google Brand（高保护）+ Amazon Brand（购买保护）
|
||||
- 竞品词：Google（截流）+ Microsoft（Bing 独家流量）
|
||||
- 产品词：Google + Amazon（不同意图阶段）
|
||||
- 漏斗上层：Google Display/Video + YouTube
|
||||
```
|
||||
|
||||
### Platform-Specific Feature Exploitation
|
||||
- **Google**：Smart Bidding + Performance Max + Broad Match + AI
|
||||
- **Microsoft**：LinkedIn 受众定向（B2B）+ 更低 CPC + Google 迁移便利
|
||||
- **Amazon**：购买意图流量 + DSP + AMC 受众分析
|
||||
|
||||
## Unified Measurement Approach
|
||||
|
||||
### Attribution Challenges
|
||||
- **Last-click 归因偏差**：Amazon 通常在漏斗底部，导致 Google Display 贡献被低估
|
||||
- **Cross-device**：用户可能在手机研究、PC 搜索、线下购买
|
||||
- **Platform silos**：各平台独立追踪，缺乏统一视图
|
||||
|
||||
### Measurement Solutions
|
||||
- **Google Analytics 4（GA4）**：跨平台归因（需 UTM + 各平台 API 集成）
|
||||
- **Amazon AMC（Amazon Marketing Cloud）**：亚马逊生态内的跨触点归因
|
||||
- **Incrementality Testing**：衡量各平台真实增量贡献
|
||||
- **Data-Driven Attribution**：ML-based 归因模型
|
||||
|
||||
## Cannibalization Prevention
|
||||
|
||||
| 症状 | 原因 | 解决方案 |
|
||||
|------|------|---------|
|
||||
| 跨平台 ROAS 均下降 | 关键词重叠，内部竞争 | 差异化关键词策略 |
|
||||
| 总转化量不变但成本上升 | 多平台分摊自然流量 | Incrementality 测试验证 |
|
||||
| 品牌词跨平台 CPC 上升 | 内部竞标 | 统一品牌词竞价策略 |
|
||||
|
||||
## Connections
|
||||
- [[GoogleAds]]：跨平台策略的核心平台之一
|
||||
- [[MicrosoftAdvertising]]：Google 之外的搜索广告补充
|
||||
- [[AmazonAds]]：购买意图漏斗底部的专属平台
|
||||
- [[IncrementalityTesting]]：衡量跨平台真实增量贡献
|
||||
- [[BudgetPacing]]：跨平台预算分配是 pacing 的高级形式
|
||||
39
wiki/concepts/Cultural-Authenticity.md
Normal file
39
wiki/concepts/Cultural-Authenticity.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: "Cultural Authenticity"
|
||||
type: concept
|
||||
tags: []
|
||||
last_updated: 2026-05-15
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Cultural Authenticity（文化真实性）——AI 生成内容中确保文化元素（建筑、服饰、符号、照明）准确反映目标文化真实生活现实的原则。文化真实性不是"代表性"的同义词——它要求更深层次的准确性：主体必须被正确锚定在其实际环境中。
|
||||
|
||||
## Core Failures AI Models Exhibit
|
||||
|
||||
1. **Architectural Inaccuracy**：不正确的建筑风格（东亚城市背景出现西式穹顶）
|
||||
2. **Lighting Bias**：照明预设适合浅肤色，不适合深肤色（hyper-saturated artificial lighting）
|
||||
3. **Gibberish Cultural Text**：非英语文字/符号被渲染为乱码或冒犯性字符
|
||||
4. **Exoticism Bias**：将文化背景"异域化"（将正常城市背景渲染为异国情调）
|
||||
5. **Hero-Symbol Composition**：文化符号（新月、佛像等）被放大为构图焦点而失去原本意义
|
||||
|
||||
## Technical Counter-Measures
|
||||
|
||||
Inclusive Visuals Specialist 的技术应对：
|
||||
|
||||
- **显式环境锚定**："In a modern, sunlit architectural office in Nairobi, Kenya. The glass walls overlook the city skyline."
|
||||
- **否定性符号约束**："No text or symbols on whiteboards"
|
||||
- **正确照明定义**："The lighting is soft and directional, expertly graded to highlight the richness of her skin tone without washing out highlights."
|
||||
- **Intersectional Specificity**：文化真实性必须与 intersectionality 结合，不能脱离具体人物
|
||||
|
||||
## Related Concepts
|
||||
|
||||
- [[Intersectionality]]
|
||||
- [[Negative Prompting]]
|
||||
- [[Sociological Accuracy]]
|
||||
- [[Inclusive Visuals Specialist]]
|
||||
|
||||
## Aliases
|
||||
|
||||
- 文化准确性
|
||||
- 文化真实性检验
|
||||
25
wiki/concepts/Cultural-Ecology.md
Normal file
25
wiki/concepts/Cultural-Ecology.md
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: "Cultural Ecology"
|
||||
type: concept
|
||||
tags: ["anthropology", "ecology", "environment", "subsistence", "steward"]
|
||||
last_updated: 2026-04-25
|
||||
---
|
||||
|
||||
## Definition
|
||||
文化生态学——研究**环境如何塑造文化**，以及**文化又如何反过来塑造和适应环境**的跨学科框架。强调物质条件（气候、地形、资源）对社会组织的约束作用，同时拒绝简单的地理/文化决定论。
|
||||
|
||||
## Core Framework
|
||||
- **文化核心（Cultural Core）**：生计模式和与技术环境互动直接相关的社会制度
|
||||
- **多线进化（Multilinear Evolution）**：不同环境可能独立产生相似的适应方案
|
||||
- **生态系统**：人类群体与环境形成的动态适应系统，具有反馈回路
|
||||
- **Pigs and People**（Rappaport）：巴布亚新几内亚 Tsembaga 人的仪式性猪屠杀，是环境调节机制的文化表达
|
||||
|
||||
## Key Thinkers
|
||||
- Julian Steward（文化生态学创始人）
|
||||
- Roy Rappaport（生态系统研究）
|
||||
- Marvin Harris（文化唯物论）
|
||||
|
||||
## Connections
|
||||
- [[Anthropologist-Agent]] ← uses_framework ← [[Cultural-Ecology]]
|
||||
- [[Functionalism]] ← related_to ← [[Cultural-Ecology]]
|
||||
- [[Polanyi-Exchange]] ← influenced_by ← [[Cultural-Ecology]]
|
||||
36
wiki/concepts/Cultural-Intelligence.md
Normal file
36
wiki/concepts/Cultural-Intelligence.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: "Cultural Intelligence"
|
||||
type: concept
|
||||
tags: [cultural-intelligence, cross-cultural, internationalization, ux-design]
|
||||
sources: [specialized-cultural-intelligence-strategist]
|
||||
last_updated: 2026-05-29
|
||||
---
|
||||
|
||||
## Definition
|
||||
文化智能（Cultural Intelligence, CQ）——一种跨文化适应能力，使个人或系统能够在不同文化背景下有效运作、沟通和建立信任。区别于 IQ（认知智能）和 EQ（情绪智能），CQ 专门衡量文化适应性，包括：对文化差异的认知理解（Cognitive CQ）、在跨文化情境中的行为适应能力（Physical CQ）、对文化情境的内在动机和信心（Metacognitive CQ）。
|
||||
|
||||
## In the Context of AI Agents
|
||||
在 AI Agent 设计中，CQ 体现为：
|
||||
- 检测和消除软件开发中的隐性排斥（Invisible Exclusion）
|
||||
- 在生成内容前自主研究特定文化的尊重和赋权表征标准
|
||||
- 理解不同文化对颜色、图标、数字、日期格式的差异化语义
|
||||
|
||||
## Core Dimensions
|
||||
- **认知 CQ（Cognitive CQ）**：文化知识——理解不同文化的价值观、习俗、社会规范和商业惯例
|
||||
- **元认知 CQ（Metacognitive CQ）**：文化意识——在跨文化交流中保持对文化假设的觉察和反思
|
||||
- **动机 CQ（Motivational CQ）**：文化好奇——主动学习和适应不同文化的内在驱动力
|
||||
- **行为 CQ（Behavioral CQ）**：文化适应——在不同文化情境中灵活调整语言、行为和沟通方式
|
||||
|
||||
## Related Concepts
|
||||
- [[Architectural Empathy]]（结构性同理心）：CQ 在软件设计中的实践框架
|
||||
- [[Invisible-Exclusion]]（隐性排斥）：CQ 所诊断的核心问题类型
|
||||
- [[Global-First-Architecture]]（全局优先架构）：CQ 在技术架构中的实施方法
|
||||
- [[Cultural Humility]]（文化谦逊）：CQ 的基础原则——承认知识不完整，持续学习
|
||||
|
||||
## Key Distinction: CQ vs. Cultural Competence
|
||||
| 维度 | 文化能力（Cultural Competence） | 文化智能（Cultural Intelligence） |
|
||||
|------|------------------------------|-------------------------------|
|
||||
| 假设 | 可以达到"文化熟练"终点 | 强调持续学习和适应 |
|
||||
| 重点 | 知识和技能的集合 | 动态的、可发展的能力 |
|
||||
| 态度 | 倾向于"了解"其他文化 | 承认"不了解"并保持好奇 |
|
||||
| 来源 | 西方学术框架 | 跨文化心理学（ Earley & Ang, 2003） |
|
||||
76
wiki/concepts/Curiosity-Driven-Bug-Discovery.md
Normal file
76
wiki/concepts/Curiosity-Driven-Bug-Discovery.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: "Curiosity-Driven Bug Discovery"
|
||||
type: concept
|
||||
tags: []
|
||||
last_updated: 2026-05-02
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
通过主动追问系统假设（而非被动等待测试失败）来发现高危 Bug 的方法论——将"未言明的假设"显式化，并在它们导致故障前将其消灭。
|
||||
|
||||
## Overview
|
||||
|
||||
大多数生产环境中的严重 Bug 并非来自代码错误，而是来自未被显式记录的**假设**。这些假设在代码编写时被默许存在，随着系统演进逐渐失效，最终在生产环境中引发故障。Curiosity-Driven Bug Discovery 是一套系统化的追问框架，在工作流设计阶段就将这些假设显式化。
|
||||
|
||||
## Four Question Dimensions
|
||||
|
||||
### 1. 数据持久化假设（Data Persistence Assumptions）
|
||||
- 数据存储在哪里？存储是持久化还是临时性的？
|
||||
- 重启后数据是否仍然存在？
|
||||
- 数据在什么条件下被清理？
|
||||
|
||||
**追问模板**：
|
||||
> "Where is this data stored? Is the storage durable or ephemeral? What happens on restart?"
|
||||
|
||||
### 2. 网络连通性假设（Network Connectivity Assumptions）
|
||||
- Service A 能否实际到达 Service B？
|
||||
- 它们在同一个网络段吗？是否有防火墙规则？
|
||||
- 服务之间是否存在 DNS 解析延迟？
|
||||
|
||||
**追问模板**：
|
||||
> "Can service A actually reach service B? Are they on the same network? Is there a firewall rule?"
|
||||
|
||||
### 3. 时序假设（Ordering/Timing Assumptions）
|
||||
- 当前步骤假设前一个步骤已完成——但它们是并行运行的吗？
|
||||
- 什么机制确保时序正确？（健康检查？轮询？事件？锁？）
|
||||
- 超时值是否合理？
|
||||
|
||||
**追问模板**：
|
||||
> "This step assumes the previous step completed — but they run in parallel. What ensures ordering?"
|
||||
|
||||
### 4. 认证授权假设（Authentication/Authorization Assumptions）
|
||||
- 此端点在启动时被调用——但调用方是否经过身份验证？
|
||||
- 什么防止未授权访问？
|
||||
- 凭证在何时何地可用？
|
||||
|
||||
**追问模板**：
|
||||
> "This endpoint is called during setup — but is the caller authenticated? What prevents unauthorized access?"
|
||||
|
||||
## Application in Workflow Architect
|
||||
|
||||
在 `Discovery Audit Checklist` 中，每发现一个隐式工作流，Workflow Architect 必须主动用四个追问维度扫描一遍。发现的高危假设记录在 `Reality Checker Findings` 表中，标注 severity 为 Critical 或 High。
|
||||
|
||||
## Why "Curiosity-Driven"
|
||||
|
||||
"Curiosity-driven" 强调这是**主动探索**而非**被动验证**：
|
||||
- **被动验证**：已有 bug 报告 → 查找原因
|
||||
- **主动探索**：无 bug 报告 → 追问假设 → 发现潜在 bug
|
||||
|
||||
这套方法论的核心洞察：**最危险的 bug 是那些从未有人怀疑其存在的假设**。
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- 每个工作流的 Assumptions 表都被填满（非空白）
|
||||
- 假设表中的假设在后续 Sprint 中被逐一验证或修正
|
||||
- 好奇心驱动发现的 bug 数量 ≥ 被动测试发现的 bug 数量
|
||||
|
||||
## Related Concepts
|
||||
- [[Workflow-Tree-Spec]]：假设记录的载体（Assumptions 节）
|
||||
- [[Reality-Checker]]：验证假设真实性的 Agent
|
||||
- [[Discovery-Audit]]：发现隐式工作流的入口
|
||||
|
||||
## Aliases
|
||||
- Assumption Mining
|
||||
- Hypothesis-First Bug Discovery
|
||||
- Proactive Assumption Surfacing
|
||||
61
wiki/concepts/Data-Contract.md
Normal file
61
wiki/concepts/Data-Contract.md
Normal file
@@ -0,0 +1,61 @@
|
||||
---
|
||||
title: "Data Contract"
|
||||
type: concept
|
||||
tags: [data-engineering, data-quality, schema, SLA]
|
||||
sources: [engineering-data-engineer]
|
||||
last_updated: 2026-05-02
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Data Contract（数据契约）是数据生产者和消费者之间的明确协议，定义了数据的预期 schema、数据类型、SLA、所有权和消费方。数据契约是 Medallion Architecture 中 Silver→Gold 层质量保证的核心机制。
|
||||
|
||||
## Components
|
||||
|
||||
### Schema Contract
|
||||
- 字段名、类型、约束（not_null、unique、foreign key）
|
||||
- Schema 演化规则：允许添加 nullable 字段，禁止删除或修改类型
|
||||
- `mergeSchema=true`：允许 schema 演进，但触发告警而非自动污染下游
|
||||
|
||||
### SLA Contract
|
||||
- 刷新频率（如"每 15 分钟刷新一次"）
|
||||
- 数据新鲜度阈值（如"1 小时内必须有新数据"）
|
||||
- 可用性承诺（如"Gold 层 99.9% 可用性"）
|
||||
|
||||
### Ownership Contract
|
||||
- 数据所有者（Data Owner）
|
||||
- 数据消费者（Data Consumer）
|
||||
- 支持联系人（Support Contact）
|
||||
|
||||
## Enforcement
|
||||
|
||||
### dbt Contract Enforcement
|
||||
```yaml
|
||||
models:
|
||||
- name: silver_orders
|
||||
config:
|
||||
contract:
|
||||
enforced: true # 强制 schema 契约，类型不匹配则构建失败
|
||||
columns:
|
||||
- name: order_id
|
||||
data_type: string
|
||||
constraints:
|
||||
- type: not_null
|
||||
- type: unique
|
||||
```
|
||||
|
||||
### Great Expectations（数据质量验证）
|
||||
- 行级数据质量评分必须在 Gold 层附加
|
||||
- Null 率告警阈值（如 `customer_id` null 率从 0.1% 跳至 4.2% → 触发 PagerDuty）
|
||||
|
||||
## Key Rules
|
||||
|
||||
- **Schema 漂移必须告警**：不得静默损坏下游数据
|
||||
- **Null 处理必须显式**：不得隐式将 null 传播到 Gold 层
|
||||
- **发布前必须与消费者确认**：数据契约签署后才能部署 Gold 层管道
|
||||
|
||||
## Related Concepts
|
||||
- [[Medallion Architecture]]
|
||||
- [[Great Expectations]]（数据质量验证工具）
|
||||
- [[Data Lineage]]
|
||||
- [[SCD Type 2]]
|
||||
35
wiki/concepts/Dataview.md
Normal file
35
wiki/concepts/Dataview.md
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: "Dataview"
|
||||
type: concept
|
||||
tags: [tool, obsidian, plugin, query]
|
||||
sources: [karpathy-最新分享-用-llm-搭建个人知识库-告别-rag-的低效循环]
|
||||
last_updated: 2026-04-20
|
||||
---
|
||||
|
||||
## Aliases
|
||||
- Obsidian Dataview 插件
|
||||
- DataviewJS
|
||||
|
||||
## Definition
|
||||
Obsidian 的社区插件，对页面 YAML frontmatter 做数据库式查询，自动生成动态表格和列表。是 LLM Wiki 的可选增强工具。
|
||||
|
||||
## LLM Wiki Usage
|
||||
让 AI 在每个 Wiki 页面的 frontmatter 里写上结构化元数据（如 `type`、`date`、`tags`、`source_count`），然后用 Dataview 查询生成动态报表。
|
||||
|
||||
## Example Query
|
||||
````markdown
|
||||
```dataview
|
||||
TABLE title, date, tags
|
||||
FROM "wiki/sources"
|
||||
SORT date DESC
|
||||
```
|
||||
````
|
||||
|
||||
## Practical Value
|
||||
- 页面少时价值有限，Wiki 规模大时（数百页面）报表价值显著
|
||||
- 老张（[[laozhang2579]]）观点："多到一定程度或者想用元数据查询方式习惯的可以考虑，我是直接用索引文件配合 Claude 的文件检索"
|
||||
- 安装：设置 → 第三方插件 → 社区插件市场 → 搜索 "Dataview" → 安装并启用
|
||||
|
||||
## Connections
|
||||
- [[Dataview]] ← 可选增强 → [[LLM Wiki]]
|
||||
- [[Dataview]] ← 插件 → [[Obsidian]]
|
||||
@@ -1,28 +1,47 @@
|
||||
---
|
||||
title: "Default Bias"
|
||||
type: concept
|
||||
tags: [behavioral-psychology, ux, nudge, persuasion]
|
||||
last_updated: 2026-04-20
|
||||
---
|
||||
|
||||
## Definition
|
||||
默认偏差（Default Bias）指用户倾向于接受预置选项而不主动修改的行为心理倾向。在软件交互中，通过预设默认行为或预填内容，降低用户决策摩擦，提高行动完成率。
|
||||
|
||||
## Mechanism
|
||||
1. **预填内容**：系统自动生成回复/草稿，用户只需确认或修改
|
||||
2. **预选选项**：智能推荐最佳选项，用户一键接受
|
||||
3. **默认同意**：预勾选最优行为选项，用户需主动取消而非选择
|
||||
|
||||
## Applications
|
||||
- 邮件回复草稿自动生成，一键发送
|
||||
- 表单字段智能预填
|
||||
- 隐私设置默认最优选项
|
||||
- 通知频率默认静音，用户按需开启
|
||||
|
||||
## Related Concepts
|
||||
- [[Nudge Theory]]：推力理论的组成部分
|
||||
- [[Cognitive Load Reduction]]：通过减少决策选项降低认知负荷
|
||||
- [[Gamification]]：可与游戏化结合增强默认选项接受率
|
||||
|
||||
## Source
|
||||
- [[Behavioral Nudge Engine]] — 核心应用场景
|
||||
---
|
||||
title: "Default Bias"
|
||||
type: concept
|
||||
tags: []
|
||||
sources: ["product-behavioral-nudge-engine"]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Default Bias（默认偏见）是一种心理现象：人们倾向于接受预设选项，即使提供退出选项也有很高概率保持默认状态。在软件交互设计中，通过预先填充行动草案并以「确认/修改」框架呈现，可大幅降低用户的决策摩擦和行动阻力。
|
||||
|
||||
## Mechanism
|
||||
|
||||
- **核心策略**：不要问用户「要不要做」，而是问「这样做好吗」
|
||||
- **行为公式**：「已起草 + 一键确认」= 最小阻力路径
|
||||
- **典型应用**：邮件回复草稿、通知设置、文档模板确认、支付流程
|
||||
- **道德边界**：必须提供真实的「opt-out」退出选项，不可隐藏或误导
|
||||
|
||||
## Example
|
||||
|
||||
> "I've drafted a thank-you reply for this 5-star review. Should I send it, or do you want to edit?"
|
||||
|
||||
这个示例展示：系统不仅起草了回复，还主动推进了决策——用户只需点击「发送」即可完成，否则才需要介入修改。
|
||||
|
||||
## Why It Works
|
||||
|
||||
1. **减少认知负担**：用户无需从零开始组织语言
|
||||
2. **消除启动摩擦**：最大的阻力在于「开始」，草案消除了这一步
|
||||
3. **利用惰性**：在低介入成本时，用户倾向于保持默认状态
|
||||
4. **正向锚定**：用户面对自己的内容比面对空白更有动力编辑
|
||||
|
||||
## Related Concepts
|
||||
|
||||
- [[Cognitive Load Reduction]] — 默认偏见是降低认知负荷的核心手段
|
||||
- [[Nudge Theory]] — 默认选项是 Nudge 的经典应用
|
||||
- [[Friction Reduction]] — 减少用户行动阻力的更广泛策略
|
||||
|
||||
## Risks & Ethical Considerations
|
||||
|
||||
- 过度使用可能引发用户「被操控」感，损害信任
|
||||
- 必须提供真实退出选项，不可暗设陷阱
|
||||
- 高风险决策（财务、法律）场景应谨慎使用
|
||||
|
||||
## Connections
|
||||
|
||||
- [[Behavioral Nudge Engine]] — 核心应用场景：任务推进、通知确认、内容发布
|
||||
|
||||
51
wiki/concepts/Defect-Prediction.md
Normal file
51
wiki/concepts/Defect-Prediction.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: "Defect Prediction"
|
||||
type: concept
|
||||
tags: [testing, machine-learning, quality]
|
||||
sources: [testing-test-results-analyzer]
|
||||
last_updated: 2026-04-28
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
缺陷预测——使用机器学习模型基于代码指标和历史缺陷数据，预测哪些代码区域最可能包含缺陷，指导测试资源的定向投入。
|
||||
|
||||
## Approach
|
||||
|
||||
### Feature Engineering (from TestResultsAnalyzer)
|
||||
|
||||
```python
|
||||
from sklearn.ensemble import RandomForestClassifier
|
||||
from sklearn.model_selection import train_test_split
|
||||
|
||||
# 特征：代码指标
|
||||
features = extract_code_metrics() # 圈复杂度、代码行数、变更频率等
|
||||
historical_defects = load_historical_defect_data() # 历史缺陷标签
|
||||
|
||||
# 训练/测试分割
|
||||
X_train, X_test, y_train, y_test = train_test_split(
|
||||
features, historical_defects, test_size=0.2, random_state=42
|
||||
)
|
||||
|
||||
# Random Forest 分类器
|
||||
model = RandomForestClassifier(n_estimators=100, random_state=42)
|
||||
model.fit(X_train, y_train)
|
||||
|
||||
# 预测 + 置信度 + 特征重要性
|
||||
predictions = model.predict_proba(features)
|
||||
feature_importance = model.feature_importances_
|
||||
accuracy = model.score(X_test, y_test)
|
||||
```
|
||||
|
||||
### Key Metrics
|
||||
|
||||
- **Prediction Accuracy**：模型在测试集上的准确率，目标 ≥ 85%。
|
||||
- **Feature Importance**：哪些代码指标（圈复杂度、变更频率、代码行数等）对缺陷预测最有预测力。
|
||||
- **Confidence Score**：每个预测结果附带置信度评分。
|
||||
|
||||
## Connections
|
||||
|
||||
- [[Statistical-Analysis]]：模型验证需统计显著性检验。
|
||||
- [[Test-Coverage-Analysis]]：预测的高风险区域优先增加测试覆盖率。
|
||||
- [[Release-Readiness-Assessment]]：缺陷预测结果纳入整体发布就绪度评估。
|
||||
- [[Quality-Metrics]]：缺陷密度是预测模型的目标变量。
|
||||
48
wiki/concepts/Dev-QA-Loop.md
Normal file
48
wiki/concepts/Dev-QA-Loop.md
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: "Dev↔QA Loop"
|
||||
type: concept
|
||||
tags: [multi-agent, quality, devops, nexus]
|
||||
sources: [executive-brief, quickstart, workflow-startup-mvp]
|
||||
last_updated: 2026-05-01
|
||||
aliases:
|
||||
- Dev QA Loop
|
||||
- Build-Test Loop
|
||||
- Dev-Test-Retry Loop
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Dev↔QA 循环（Dev↔QA Loop）—— 构建→测试→通过/失败→重试的持续质量循环，最多允许 3 次迭代；FAIL 时触发修复重试，PASS 时推进到下一阶段。
|
||||
|
||||
## Mechanism
|
||||
|
||||
```
|
||||
开发 Agent 交付实现
|
||||
↓
|
||||
QA Agent 执行质量验证
|
||||
↓
|
||||
┌──────────────────────────┐
|
||||
│ PASS? │
|
||||
├──────────┬───────────────┤
|
||||
│ 是 │ 否 │
|
||||
│ ↓ │ ↓ │
|
||||
│ 推进下一阶段 │ 进入修复循环 │
|
||||
│ │ (重试 N/3) │
|
||||
└──────────┴───────────────┘
|
||||
```
|
||||
|
||||
## Quantified Impact
|
||||
|
||||
- **集成前缺陷捕获率**：95% —— 大部分缺陷在 Dev↔QA 循环中被捕获，而非等到集成阶段
|
||||
- **Phase 4 硬化时间减少**：50% —— 持续质量循环优于端到端测试
|
||||
- **最大重试次数**：3 次 —— 超过 3 次 FAIL 触发升级/上报机制
|
||||
|
||||
## Role in NEXUS
|
||||
|
||||
Dev↔QA 循环是 NEXUS Phase 3 Build 阶段的核心机制，也是 NEXUS 的四大核心原则之一（Quality Gates / Dev↔QA Loop / Handoffs / Evidence Over Claims）。
|
||||
|
||||
## Related Concepts
|
||||
|
||||
- [[Quality Gate]]：Dev↔QA 循环是质量门控体系的具体实现机制
|
||||
- [[Reality Checker]]：Dev↔QA 循环 PASS 后，最终质量权威由 Reality Checker 确认
|
||||
- [[Evidence Over Claims]]：循环中的验证必须基于证据而非口头断言
|
||||
@@ -1,76 +1,78 @@
|
||||
---
|
||||
title: "Discrimination Metrics"
|
||||
type: concept
|
||||
tags: [model-evaluation, classification-metrics, model-performance]
|
||||
last_updated: 2026-04-25
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
判别能力指标（Discrimination Metrics）衡量模型区分正例与负例的能力——给定一个随机正例和一个随机负例，模型有多大概率给正例更高的分数。区别于校准（衡量概率准确性），判别度衡量排序正确性。
|
||||
|
||||
## Core Metrics
|
||||
|
||||
### AUC (Area Under the ROC Curve)
|
||||
- ROC 曲线下面积，取值 [0.5, 1.0]
|
||||
- 0.5 = 随机猜测，1.0 = 完美区分
|
||||
- 解读：给定随机正例和随机负例，有 AUC 概率给正例更高分数
|
||||
- **优势**：阈值无关，对类别不平衡相对稳健
|
||||
|
||||
### Gini Coefficient
|
||||
- $Gini = 2 \times AUC - 1$
|
||||
- 取值 [0, 1.0]，与 AUC 线性等价
|
||||
- 金融行业常用（信用卡评分、信贷风控）
|
||||
- 监管报告标准指标
|
||||
|
||||
### KS Statistic (Kolmogorov-Smirnov)
|
||||
- 两个累积分布函数（正例 vs 负例）之间的最大垂直距离
|
||||
- $KS = \max_t |F_{pos}(t) - F_{neg}(t)|$
|
||||
- 取值 [0, 1.0]；KS > 0.2 通常认为有区分能力
|
||||
- **优势**：不依赖阈值，提供最佳分割点位置信息
|
||||
|
||||
### Additional Metrics
|
||||
| Metric | Formula | 适用场景 |
|
||||
|--------|---------|---------|
|
||||
| F1 Score | $2 \times \frac{precision \times recall}{precision + recall}$ | 类别不平衡 |
|
||||
| RMSE | $\sqrt{\frac{1}{n}\sum(y_i - \hat{y}_i)^2}$ | 回归模型 |
|
||||
| Log Loss | $-\frac{1}{N}\sum[y_i \log p_i + (1-y_i)\log(1-p_i)]$ | 概率质量 |
|
||||
|
||||
## Usage
|
||||
|
||||
```python
|
||||
from sklearn.metrics import roc_auc_score, f1_score
|
||||
from scipy.stats import ks_2samp
|
||||
|
||||
def discrimination_report(y_true, y_score):
|
||||
auc = roc_auc_score(y_true, y_score)
|
||||
gini = 2 * auc - 1
|
||||
ks_stat, ks_pval = ks_2samp(y_score[y_true == 1], y_score[y_true == 0])
|
||||
return {
|
||||
"AUC": round(auc, 4),
|
||||
"Gini": round(gini, 4),
|
||||
"KS": round(ks_stat, 4),
|
||||
"KS_pvalue": round(ks_pval, 6),
|
||||
}
|
||||
```
|
||||
|
||||
## Model QA 中的应用
|
||||
|
||||
Model QA Specialist 执行以下判别能力审计：
|
||||
1. **全数据切片分析**：在 Train/Validation/Test/OOT 四个数据切片上分别计算 AUC/Gini/KS
|
||||
2. **子群体性能**：在性别/年龄/地区等受保护属性上分别测试，发现公平性隐患
|
||||
3. **时间稳定性**：跨 OOT 窗口追踪 AUC/Gini 趋势，识别性能衰减
|
||||
4. **冠军-挑战者对比**：Proposed model vs. incumbent production model，量化相对提升
|
||||
|
||||
## Relationship
|
||||
|
||||
- **被依赖** [[Calibration-Testing]]：先确认判别能力（KS > 0.2, AUC > 0.7），再测试校准
|
||||
- **依赖** [[Population-Stability-Index]]：PSI 监控输入稳定性，判别指标监控输出健康度
|
||||
- **依赖** [[SHAP]]：判别指标提供"是否好"的答案，SHAP 解释"为什么"
|
||||
- **支撑** [[specialized-model-qa]]（Source）：Model QA Specialist 的核心性能评估步骤
|
||||
|
||||
## Key Insights
|
||||
|
||||
- **判别度 vs 校准**：高 AUC 模型仍可能在特定概率区间严重校准偏差；两者必须同时评估
|
||||
- **KS vs AUC**：KS 对尾部区分更敏感（抓坏人），AUC 对整体排序更均衡
|
||||
- **监管门槛**：金融风控通常要求 Gini > 0.4（相当于 AUC > 0.7）方可上线
|
||||
---
|
||||
title: "Discrimination Metrics"
|
||||
type: concept
|
||||
tags: [model-evaluation, classification-metrics, model-performance]
|
||||
sources:
|
||||
- specialized-model-qa
|
||||
last_updated: 2026-05-29
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
判别能力指标（Discrimination Metrics）衡量模型区分正例与负例的能力——给定一个随机正例和一个随机负例，模型有多大概率给正例更高的分数。区别于校准（衡量概率准确性），判别度衡量排序正确性。
|
||||
|
||||
## Core Metrics
|
||||
|
||||
### AUC (Area Under the ROC Curve)
|
||||
- ROC 曲线下面积，取值 [0.5, 1.0]
|
||||
- 0.5 = 随机猜测，1.0 = 完美区分
|
||||
- 解读：给定随机正例和随机负例，有 AUC 概率给正例更高分数
|
||||
- **优势**：阈值无关，对类别不平衡相对稳健
|
||||
|
||||
### Gini Coefficient
|
||||
- $Gini = 2 \times AUC - 1$
|
||||
- 取值 [0, 1.0]，与 AUC 线性等价
|
||||
- 金融行业常用（信用卡评分、信贷风控）
|
||||
- 监管报告标准指标
|
||||
|
||||
### KS Statistic (Kolmogorov-Smirnov)
|
||||
- 两个累积分布函数（正例 vs 负例）之间的最大垂直距离
|
||||
- $KS = \max_t |F_{pos}(t) - F_{neg}(t)|$
|
||||
- 取值 [0, 1.0]；KS > 0.2 通常认为有区分能力
|
||||
- **优势**：不依赖阈值，提供最佳分割点位置信息
|
||||
|
||||
### Additional Metrics
|
||||
| Metric | Formula | 适用场景 |
|
||||
|--------|---------|---------|
|
||||
| F1 Score | $2 \times \frac{precision \times recall}{precision + recall}$ | 类别不平衡 |
|
||||
| RMSE | $\sqrt{\frac{1}{n}\sum(y_i - \hat{y}_i)^2}$ | 回归模型 |
|
||||
| Log Loss | $-\frac{1}{N}\sum[y_i \log p_i + (1-y_i)\log(1-p_i)]$ | 概率质量 |
|
||||
|
||||
## Usage
|
||||
|
||||
```python
|
||||
from sklearn.metrics import roc_auc_score, f1_score
|
||||
from scipy.stats import ks_2samp
|
||||
|
||||
def discrimination_report(y_true, y_score):
|
||||
auc = roc_auc_score(y_true, y_score)
|
||||
gini = 2 * auc - 1
|
||||
ks_stat, ks_pval = ks_2samp(y_score[y_true == 1], y_score[y_true == 0])
|
||||
return {
|
||||
"AUC": round(auc, 4),
|
||||
"Gini": round(gini, 4),
|
||||
"KS": round(ks_stat, 4),
|
||||
"KS_pvalue": round(ks_pval, 6),
|
||||
}
|
||||
```
|
||||
|
||||
## Model QA 中的应用
|
||||
|
||||
Model QA Specialist 执行以下判别能力审计：
|
||||
1. **全数据切片分析**：在 Train/Validation/Test/OOT 四个数据切片上分别计算 AUC/Gini/KS
|
||||
2. **子群体性能**：在性别/年龄/地区等受保护属性上分别测试，发现公平性隐患
|
||||
3. **时间稳定性**：跨 OOT 窗口追踪 AUC/Gini 趋势，识别性能衰减
|
||||
4. **冠军-挑战者对比**：Proposed model vs. incumbent production model，量化相对提升
|
||||
|
||||
## Relationship
|
||||
|
||||
- **被依赖** [[Calibration-Testing]]：先确认判别能力（KS > 0.2, AUC > 0.7），再测试校准
|
||||
- **依赖** [[Population-Stability-Index]]：PSI 监控输入稳定性，判别指标监控输出健康度
|
||||
- **依赖** [[SHAP]]：判别指标提供"是否好"的答案，SHAP 解释"为什么"
|
||||
- **支撑** [[specialized-model-qa]]（Source）：Model QA Specialist 的核心性能评估步骤
|
||||
|
||||
## Key Insights
|
||||
|
||||
- **判别度 vs 校准**：高 AUC 模型仍可能在特定概率区间严重校准偏差；两者必须同时评估
|
||||
- **KS vs AUC**：KS 对尾部区分更敏感（抓坏人），AUC 对整体排序更均衡
|
||||
- **监管门槛**：金融风控通常要求 Gini > 0.4（相当于 AUC > 0.7）方可上线
|
||||
|
||||
61
wiki/concepts/Divio-Documentation-System.md
Normal file
61
wiki/concepts/Divio-Documentation-System.md
Normal file
@@ -0,0 +1,61 @@
|
||||
---
|
||||
title: "Divio Documentation System"
|
||||
type: concept
|
||||
tags: ["documentation", "knowledge-management", "methodology"]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Definition
|
||||
Divio Documentation System 是由 [Divio](https://www.divio.com) 提出的文档分类框架，将技术文档分为四个互不重叠的象限，每个象限有明确的目的、受众和写作风格要求。
|
||||
|
||||
## Four Quadrants
|
||||
|
||||
### 1. Tutorial（教程）— 学习导向
|
||||
- **目的**：让读者学会使用某个工具或技术
|
||||
- **受众**：新手、入门者
|
||||
- **风格**：循循善诱，像老师带学生一样，解释"为什么这样做"
|
||||
- **关键特征**：从零开始、有明确起点和终点、成功结果可验证
|
||||
- **反面教材**：不要写成操作手册（那是 How-to）或参考手册（那是 Reference）
|
||||
|
||||
### 2. How-to Guide（操作指南）— 任务导向
|
||||
- **目的**：帮助读者完成特定任务
|
||||
- **受众**：已有基础知识的开发者
|
||||
- **风格**：实用导向，提供解决具体问题的步骤
|
||||
- **关键特征**：面向结果、不解释基础知识、假设读者知道基本操作
|
||||
- **反面教材**：不要写成教程（不需要从零开始）或参考文档（不需要穷举选项）
|
||||
|
||||
### 3. Reference（参考文档）— 信息导向
|
||||
- **目的**：准确描述系统功能，提供查找式的信息检索
|
||||
- **受众**：需要精确信息的开发者
|
||||
- **风格**：简洁、精确、格式一致、不含解释
|
||||
- **关键特征**：结构化（按字母/功能分组）、完整枚举所有选项、自动生成
|
||||
- **反面教材**：不要混入教程内容或解释"为什么"，那会稀释参考价值
|
||||
|
||||
### 4. Explanation（解释文档）— 理解导向
|
||||
- **目的**：帮助读者深入理解某个主题，提供背景和上下文
|
||||
- **受众**：想理解"为什么"的开发者
|
||||
- **风格**：探索性、讨论性、允许不同观点
|
||||
- **关键特征**：不提供步骤、不列举选项、聚焦概念和原理
|
||||
- **反面教材**：不要写成 How-to（不需要完成任务）或 Reference（不需要列举信息）
|
||||
|
||||
## Key Rules
|
||||
|
||||
### 绝对禁止：混合象限
|
||||
- 一个文档页面只属于一个象限
|
||||
- 混合会导致读者困惑（不知道该看哪部分）和作者维护困难
|
||||
- 常见错误：把"什么是 X"（Explanation）和"如何用 X"（How-to）写在同一页
|
||||
|
||||
### 绝对禁止：在参考文档中写教程内容
|
||||
- API 参考文档只描述接口，不教如何使用
|
||||
- Tutorial 是独立页面
|
||||
|
||||
### 文档类型与工具的对应关系
|
||||
| 类型 | 推荐工具 | 生成方式 |
|
||||
|------|---------|---------|
|
||||
| Tutorial | Jupyter Notebook, Docusaurus | 人工编写 |
|
||||
| How-to | Docusaurus, MkDocs | 人工编写 |
|
||||
| Reference | Sphinx, OpenAPI Generator | 自动生成 + 人工审核 |
|
||||
| Explanation | Docusaurus, MkDocs | 人工编写 |
|
||||
|
||||
## Sources
|
||||
- [[engineering-technical-writer]] — Technical Writer Agent 使用 Divio 系统组织文档写作方法论
|
||||
41
wiki/concepts/DockerHostNetworking.md
Normal file
41
wiki/concepts/DockerHostNetworking.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: "DockerHostNetworking"
|
||||
type: concept
|
||||
tags:
|
||||
- "docker"
|
||||
- "networking"
|
||||
- "container"
|
||||
sources: []
|
||||
last_updated: 2026-04-20
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
DockerHostNetworking 是 Docker 容器访问宿主机网络服务的方式。默认情况下，容器内的 `localhost` 指向容器自身而非宿主机，因此需要特殊配置才能让容器访问运行在宿主机上的服务。
|
||||
|
||||
## Why It Matters for Hermes Agent + Open WebUI
|
||||
|
||||
Open WebUI 运行在 Docker 容器中，Hermes Agent API Server 运行在宿主机上（端口 8642）。容器内必须通过特殊方式访问宿主机端口。
|
||||
|
||||
## Options
|
||||
|
||||
### Option 1: host.docker.internal（推荐 macOS/Windows）
|
||||
```bash
|
||||
docker run --add-host=host.docker.internal:host-gateway ...
|
||||
# 访问：http://host.docker.internal:8642/v1
|
||||
```
|
||||
|
||||
### Option 2: Host Networking（Linux）
|
||||
```bash
|
||||
docker run --network=host ...
|
||||
# 访问：http://localhost:8642/v1
|
||||
```
|
||||
|
||||
### Option 3: Docker Bridge IP
|
||||
```bash
|
||||
# 先查询：docker inspect bridge | grep Gateway
|
||||
docker run -e OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1 ...
|
||||
```
|
||||
|
||||
## See Also
|
||||
- [[open-webui-hermes-agent]]
|
||||
82
wiki/concepts/Docs-as-Code.md
Normal file
82
wiki/concepts/Docs-as-Code.md
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: "Docs-as-Code"
|
||||
type: concept
|
||||
tags: ["documentation", "devops", "methodology"]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Definition
|
||||
Docs-as-Code 是一种将文档视为代码的实践方法论——文档使用与代码相同的工具、流程和版本控制进行管理。
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. 版本控制
|
||||
- 文档存储在 Git 仓库中
|
||||
- 所有变更通过 Pull Request 审查
|
||||
- 保留完整变更历史，支持回滚
|
||||
|
||||
### 2. 自动化构建
|
||||
- 文档变更触发 CI/CD 流水线
|
||||
- 自动运行文档检查（spellcheck、broken links、style linting）
|
||||
- 自动部署到文档托管平台
|
||||
|
||||
### 3. 协作流程
|
||||
- 开发者可以直接在 IDE 中编辑文档
|
||||
- 使用 Markdown / reStructuredText / AsciiDoc 等代码友好格式
|
||||
- 文档评审与代码评审使用相同工具和流程
|
||||
|
||||
### 4. 自动化生成
|
||||
- API 参考文档从 OpenAPI/Swagger 规范自动生成
|
||||
- 代码示例从源代码自动提取
|
||||
- 从代码注释（docstrings/JSDoc）自动生成参考文档
|
||||
|
||||
## Tooling Ecosystem
|
||||
|
||||
### Static Site Generators
|
||||
- **Docusaurus**：Meta 出品，React 驱动，适合开源项目
|
||||
- **MkDocs**：Python 驱动，YAML 配置，Material 主题美观
|
||||
- **Sphinx**：Python 官方文档工具，reStructuredText 格式，扩展丰富
|
||||
- **VitePress**：Vue 团队出品，轻量快速，Markdown 优先
|
||||
|
||||
### Documentation Generators
|
||||
- **OpenAPI Generator / Swagger Codegen**：从 OpenAPI 规范生成多语言 SDK + 参考文档
|
||||
- **JSDoc / TypeDoc**：从代码注释生成 JS/TS 参考文档
|
||||
- **Sphinx autodoc**：从 Python docstrings 自动生成参考文档
|
||||
- **Redoc**：开源 API 文档渲染器，从 OpenAPI 规范生成可读文档
|
||||
- **Stoplight**：商业级 API 设计 + 文档平台
|
||||
|
||||
### Linting & Quality
|
||||
- **Vale**：prose linter，自定义风格规则，检查文档语法和风格一致性
|
||||
- **markdownlint**：Markdown 文件格式检查
|
||||
- ** spellchecker**：拼写检查
|
||||
- **Link Checker**：断链检测
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
### 基础设施
|
||||
- [ ] Git 仓库存储文档（与代码同一仓库或专门 docs 仓库）
|
||||
- [ ] CI/CD 流水线配置文档构建和检查
|
||||
- [ ] 选择静态站点生成器并完成初始配置
|
||||
- [ ] 配置自动化文档生成（API docs from OpenAPI/JSDoc）
|
||||
|
||||
### 质量门禁
|
||||
- [ ] Vale prose linter 规则配置
|
||||
- [ ] markdownlint 检查配置
|
||||
- [ ] 断链检查集成
|
||||
- [ ] 拼写检查集成
|
||||
|
||||
### 发布流程
|
||||
- [ ] 配置自动部署到 GitHub Pages / Read the Docs / Netlify
|
||||
- [ ] 文档变更触发 PR 审查流程
|
||||
- [ ] 定义文档所有者（维护者）职责
|
||||
|
||||
### 版本管理
|
||||
- [ ] 配置多版本文档（对应软件版本）
|
||||
- [ ] 旧版本文档归档策略（标记弃用，不删除）
|
||||
|
||||
## Relationship to Technical Writing
|
||||
|
||||
Docs-as-Code 是 [[TechnicalWriter]] 的基础设施能力。[[engineering-technical-writer]] 定义了文档内容标准（Divio 系统、质量门禁、指标驱动），Docs-as-Code 提供了实现这些标准的工程化流程。两者共同构成完整的文档工程实践体系。
|
||||
|
||||
## Sources
|
||||
- [[engineering-technical-writer]] — Technical Writer Agent 核心理念：文档即代码，代码无文档视为不完整
|
||||
32
wiki/concepts/DomainDrivenDesign.md
Normal file
32
wiki/concepts/DomainDrivenDesign.md
Normal file
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: "Domain-Driven Design"
|
||||
type: concept
|
||||
tags: []
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Definition
|
||||
一种以业务领域为核心的软件设计方法论，通过建立通用语言（Ubiquitous Language）在技术和业务团队之间建立统一的沟通模型，并以有界上下文（Bounded Context）划分系统的边界。
|
||||
|
||||
## Key Patterns
|
||||
- **Bounded Context**：业务领域的清晰边界，每个上下文有独立的模型和术语
|
||||
- **Aggregate**：聚合根，负责维护业务不变量
|
||||
- **Domain Event**：领域事件，记录业务状态变化
|
||||
- **Anti-Corruption Layer**：防腐层，隔离外部系统对核心域的侵蚀
|
||||
- **Context Mapping**：上下文映射，定义不同有界上下文之间的关系（Upstream/Downstream/Conformist/Anti-Corruption）
|
||||
|
||||
## Core Principles
|
||||
- **领域优先，技术其次**：先理解业务问题，再选择技术实现
|
||||
- **通用语言**：团队中的每个人都使用同一套术语，减少沟通摩擦
|
||||
- **持续精化**：领域模型通过迭代不断深化对业务的理解
|
||||
|
||||
## Related Concepts
|
||||
- [[BoundedContext]]：DDD 中的核心边界概念
|
||||
- [[EventStorming]]：领域发现的协作技术
|
||||
|
||||
## Sources
|
||||
- [[engineering-software-architect]]
|
||||
|
||||
## Aliases
|
||||
- DDD
|
||||
- Domain-Driven Design
|
||||
58
wiki/concepts/Dual-Sign-Off.md
Normal file
58
wiki/concepts/Dual-Sign-Off.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: "Dual Sign-Off"
|
||||
type: concept
|
||||
tags: [governance, quality, NEXUS, gate-keeping]
|
||||
last_updated: 2026-05-01
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Dual Sign-Off（双重签批）是 NEXUS 多 Agent 框架的质量治理核心机制——在关键决策点，必须由**两个相互独立的不同视角**的 Gate Keeper **同时批准**，方才有效。任一方否决即为否决。
|
||||
|
||||
## 设计原理
|
||||
|
||||
单一 Gate Keeper 的盲区：
|
||||
- 仅战略视角 → 可能忽视技术可行性和工程复杂度
|
||||
- 仅技术视角 → 可能忽视业务价值和资源约束
|
||||
|
||||
Dual Sign-Off 通过**视角正交性**消除单点故障，确保：
|
||||
1. 战略决策有技术可行性支撑
|
||||
2. 技术决策有业务价值对齐
|
||||
|
||||
## 在 NEXUS 中的应用
|
||||
|
||||
### Phase 1 — 战略 + 技术双签
|
||||
|
||||
| Gate Keeper | 视角 | 验证内容 |
|
||||
|------------|------|---------|
|
||||
| [[Studio Producer]] | 战略 | 架构包是否对齐组织战略目标？ROI 是否符合预期？ |
|
||||
| [[Reality Checker]] | 技术 | 所有组件是否具备实现路径？质量门是否通过？ |
|
||||
|
||||
### Phase 2 — DevOps + QA 双签
|
||||
|
||||
| Gate Keeper | 视角 | 验证内容 |
|
||||
|------------|------|---------|
|
||||
| DevOps Automator | 基础设施 | CI/CD/IaC 是否就绪？可部署？ |
|
||||
| Evidence Collector | 质量验证 | 8 项截图证据是否全部通过？ |
|
||||
|
||||
### Dev↔QA Loop（循环内）
|
||||
|
||||
| 决策 | 条件 |
|
||||
|------|------|
|
||||
| PASS | Evidence Collector 证据通过 + Dev 确认修复 |
|
||||
| FAIL | 任何一方未通过；进入重试循环（最多3次） |
|
||||
|
||||
## 决策规则
|
||||
|
||||
- **任一方返回 REVISE** → 整体 REVISE；返回对应 Step 重做
|
||||
- **任一方返回 RESTRUCTURE** → 整体 RESTRUCTURE；重启本 Phase
|
||||
- **Evidence Over Claims**：口头确认无效，必须有截图/测试结果/日志证据
|
||||
|
||||
## 与 Quality Gate Checklist 的关系
|
||||
|
||||
Dual Sign-Off 是 Quality Gate Checklist 的**执行机制**。Quality Gate 定义"检查什么"（7项清单），Dual Sign-Off 定义"谁检查"和"如何通过"（双签规则）。
|
||||
|
||||
## Aliases
|
||||
- Dual Approval
|
||||
- Twin Gate Mechanism
|
||||
- Bifurcated Sign-Off
|
||||
47
wiki/concepts/EBUR128LoudnessNormalization.md
Normal file
47
wiki/concepts/EBUR128LoudnessNormalization.md
Normal file
@@ -0,0 +1,47 @@
|
||||
---
|
||||
title: "EBUR128LoudnessNormalization"
|
||||
type: concept
|
||||
tags: ["audio-processing", "loudness", "ffmpeg", "ebur128"]
|
||||
last_updated: 2026-05-02
|
||||
---
|
||||
|
||||
# EBUR128LoudnessNormalization（EBU R128 响度归一化）
|
||||
|
||||
## Definition
|
||||
|
||||
EBU R128 是欧洲广播联盟制定的响度归一化标准，用于确保不同来源的音频具有一致的感知响度。在 Whisper 类转录模型管道中，R128 归一化确保输入音频响度稳定，避免因音量差异导致的精度下降。
|
||||
|
||||
## Standard Parameters
|
||||
|
||||
```bash
|
||||
-af "loudnorm=I=-16:TP=-1.5:LRA=11"
|
||||
```
|
||||
|
||||
| 参数 | 含义 | 标准值 |
|
||||
|------|------|--------|
|
||||
| `I` | 综合响度（Integrated Loudness） | -16 LUFS |
|
||||
| `TP` | 真峰值（True Peak） | -1.5 dBTP |
|
||||
| `LRA` | 响度范围（Loudness Range） | 11 LU |
|
||||
|
||||
## Why -16 LUFS?
|
||||
|
||||
- 广播标准（TV/Streaming）：-24 LUFS（旧标准）→ -16 LUFS（新趋势，Netflix/YouTube）
|
||||
- Podcast/对话内容：-16 LUFS 更适合语音主导的内容
|
||||
- 过高的综合响度（>-14 LUFS）会导致语音压缩失真
|
||||
|
||||
## Pipeline Context
|
||||
|
||||
```
|
||||
原始音频 → 格式检测（ffprobe）→ EBU R128 归一化 → 重采样至 16kHz → 单声道
|
||||
```
|
||||
|
||||
## Why It Matters for Whisper
|
||||
|
||||
Whisper 对响度变化不免疫。同一段语音，-30 LUFS 的录音和 -16 LUFS 的录音，后者的WER（Word Error Rate）更低，因为响度归一化降低了动态范围，减少了模型在处理软/响片段时的注意力分散。
|
||||
|
||||
## Related Concepts
|
||||
- [[VoiceActivityDetection]] — 归一化之后的后处理
|
||||
- [[FasterWhisper]] — 归一化音频的消费者
|
||||
|
||||
## Related Sources
|
||||
- [[engineering-voice-ai-integration-engineer]]
|
||||
79
wiki/concepts/Echidna.md
Normal file
79
wiki/concepts/Echidna.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
title: "Echidna（属性化模糊测试）"
|
||||
type: concept
|
||||
tags: [blockchain, security, smart-contract, fuzzing, property-based-testing]
|
||||
sources: [blockchain-security-auditor]
|
||||
last_updated: 2026-05-30
|
||||
---
|
||||
|
||||
## Aliases
|
||||
- Echidna
|
||||
- Echidna Fuzzer
|
||||
- Property-Based Fuzzing
|
||||
|
||||
## Definition
|
||||
|
||||
Echidna 是一个属性化模糊测试（Property-Based Fuzzing）工具，专门用于智能合约安全测试。它通过随机生成交易序列，持续验证协议定义的不变性（invariants）是否始终成立。当不变性被违反时，Echidna 会生成触发该违规的具体交易序列作为 PoC。
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **定义不变性**：用 Solidity 编写断言或属性
|
||||
2. **生成随机交易**：Echidna 以随机参数调用合约函数
|
||||
3. **监控不变性**：每次状态变更后检查断言
|
||||
4. **生成 PoC**：发现违规时输出触发序列
|
||||
|
||||
## Example Test
|
||||
|
||||
```solidity
|
||||
// SPDX-License-Identifier: MIT
|
||||
pragma solidity ^0.8.24;
|
||||
|
||||
import {Test} from "forge-std/Test.sol";
|
||||
import {Vault} from "../src/Vault.sol";
|
||||
|
||||
contract EchidnaInvariantTest {
|
||||
Vault public vault;
|
||||
|
||||
constructor() {
|
||||
vault = new Vault();
|
||||
}
|
||||
|
||||
// 不变性：任何时刻总存款 = 所有用户余额之和
|
||||
function echidna_total_deposits_equals_sum() public view returns (bool) {
|
||||
return vault.totalDeposits() == vault.getSumOfBalances();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
```yaml
|
||||
# echidna-config.yaml
|
||||
testMode: assertion # 断言模式
|
||||
testLimit: 500000 # 最大测试数
|
||||
timeout: 3600 # 超时（秒）
|
||||
sender: ["0x000...1", "0x000...2"] # 发送者地址
|
||||
```
|
||||
|
||||
## Relationship to Other Tools
|
||||
|
||||
| Tool | Method | Strength |
|
||||
|------|--------|----------|
|
||||
| [[Slither]] | 静态分析 | 快速扫描，规则匹配 |
|
||||
| [[Mythril]] | 符号执行 | 深度路径覆盖 |
|
||||
| [[Echidna]] | 属性化模糊测试 | 随机交易序列，不变性验证 |
|
||||
|
||||
- **Echidna** 是 Slither 和 Mythril 的**补充**，不是替代
|
||||
- Slither 找规则性漏洞 → Echidna 找逻辑漏洞
|
||||
- Foundry 的 `forge invariant` 命令也提供类似功能
|
||||
|
||||
## Limitations
|
||||
|
||||
- 不变性定义错误会导致漏报
|
||||
- 复杂状态空间难以在合理时间覆盖
|
||||
- 需要开发者定义正确的不变性
|
||||
|
||||
## Connections
|
||||
- [[Blockchain-Security-Auditor]] ← uses ← [[Echidna]]
|
||||
- [[Foundry]] ← provides invariant testing ← [[Echidna]]
|
||||
- [[Formal-Verification]] ← complements ← [[Echidna]]
|
||||
49
wiki/concepts/EffectiveTaxRate.md
Normal file
49
wiki/concepts/EffectiveTaxRate.md
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: "Effective Tax Rate (ETR)"
|
||||
type: concept
|
||||
tags: ["tax", "finance", "kpi", "compliance"]
|
||||
last_updated: 2026-05-02
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
有效税率（Effective Tax Rate, ETR）是企业实际税负占税前收入的比例，是衡量税务筹划效果的核心 KPI。计算公式：
|
||||
|
||||
```
|
||||
ETR = 总税负 ÷ 税前收入
|
||||
```
|
||||
|
||||
## ETR vs Statutory Rate
|
||||
|
||||
| 指标 | 说明 |
|
||||
|------|------|
|
||||
| Statutory Rate | 法定税率（如美国联邦 21%） |
|
||||
| ETR | 实际有效税率（含各项抵扣和优惠） |
|
||||
| Cash Tax Rate | 实际支付现金税率（含递延税） |
|
||||
|
||||
ETR 通常低于 Statutory Rate，因为存在税收抵免（Tax Credits）、递延（Deferred Income）和国际税率差异等优化空间。
|
||||
|
||||
## ETR Waterfall Components
|
||||
|
||||
典型 ETR 瀑布分解：
|
||||
- Federal Statutory Tax（联邦法定税率）
|
||||
- State & Local Taxes（SALT）
|
||||
- International Rate Differential（国际税率差异）
|
||||
- R&D Tax Credits（R&D 税收抵免）
|
||||
- QBI Deduction（合格商业收入扣除）
|
||||
- Other Permanent/Temporary Adjustments（其他永久/暂时性调整）
|
||||
|
||||
## Target
|
||||
|
||||
- **[[finance-tax-strategist]]** 目标：ETR ≤ 行业同行中位数
|
||||
- 成功标准：审计调整 < 2% 总税负
|
||||
|
||||
## Sources
|
||||
|
||||
- [[finance-tax-strategist]]
|
||||
|
||||
## Related Concepts
|
||||
|
||||
- [[TransferPricing]]
|
||||
- [[GILTI]]
|
||||
- [[BEAT]]
|
||||
46
wiki/concepts/Elasticity.md
Normal file
46
wiki/concepts/Elasticity.md
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: "Elasticity"
|
||||
type: concept
|
||||
tags: [sre, cloud, scalability, reliability, capacity-planning]
|
||||
last_updated: 2026-04-20
|
||||
---
|
||||
|
||||
# Elasticity
|
||||
|
||||
弹性（Elasticity）是指系统在无需人工干预的情况下，根据需求动态调整容量的能力，是云原生的核心特性之一。
|
||||
|
||||
## Definition
|
||||
真正的弹性需要**策略、测试和对瓶颈的认知**。它不仅仅是自动扩容，而是一个包含规划、执行和验证的完整体系。
|
||||
|
||||
## Core Requirements
|
||||
1. **策略（Policy）**：明确定义扩容和缩容的规则
|
||||
2. **测试（Testing）**：在非生产环境验证弹性行为
|
||||
3. **瓶颈认知（Bottleneck Awareness）**：理解系统的性能瓶颈在哪里
|
||||
|
||||
## Elasticity vs. Autoscaling
|
||||
|
||||
| Aspect | [[Autoscaling]] | Elasticity |
|
||||
|--------|-----------------|-----------|
|
||||
| 性质 | 工具/机制 | 设计原则/能力 |
|
||||
| 范围 | 单一维度（资源） | 多维度（容量、性能、成本） |
|
||||
| 前瞻性 | 被动响应 | 主动规划 |
|
||||
| 人类角色 | 可能被排除 | 必须参与 |
|
||||
|
||||
## Key Insight
|
||||
Autoscaling 是实现弹性的**工具之一**，但 Autoscaling 本身不等同于弹性。缺乏策略和测试的 Autoscaling 可能在故障期间造成更大损害。
|
||||
|
||||
## Implementation Pillars
|
||||
- **Capacity Planning**：预测需求，提前规划
|
||||
- **Cost Optimization**：在弹性和成本之间取得平衡
|
||||
- **Observability**：通过遥测数据理解系统边界
|
||||
- **Chaos Engineering**：通过实验验证系统韧性
|
||||
|
||||
## Related Concepts
|
||||
- [[Autoscaling]]
|
||||
- [[Scalability]]
|
||||
- [[Cost-Optimization]]
|
||||
- [[Observability]]
|
||||
- [[Resilience]]
|
||||
|
||||
## Source
|
||||
- SRE Weekly Issue #513 — [[sre-weekly-issue-513]]
|
||||
@@ -1,39 +1,64 @@
|
||||
---
|
||||
title: "Encounter Design"
|
||||
type: concept
|
||||
tags: []
|
||||
last_updated: 2026-04-26
|
||||
tags: ["game-design", "level-design", "combat-design", "player-balance", "tactics"]
|
||||
sources: ["level-designer.md"]
|
||||
last_updated: 2026-05-07
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
遭遇战设计（Encounter Design）是在游戏关卡中为战斗、挑战或关键互动节点制定规则与布局的学科。每个遭遇必须可读、公平且令人难忘。
|
||||
Encounter Design（遭遇战设计）是游戏关卡设计中对战斗、挑战或关键交互节点的规划方法论。**核心要求：每场遭遇战必须同时具备进入读时、多种战术选项和撤退位置——三者缺一则战斗不公平**。
|
||||
|
||||
## Core Standards
|
||||
## Three Mandatory Elements
|
||||
|
||||
### Three Mandatory Components
|
||||
每个战斗遭遇必须包含：
|
||||
1. **入口读图时间（Entry Read Time）**：玩家在进入遭遇前能看到战场全貌
|
||||
2. **多种战术选项（Multiple Tactical Approaches）**：至少 2 种可行战术，让玩家做有意义的选择
|
||||
3. **退守位置（Fallback Position）**：玩家处于劣势时可以安全撤退或重整的空间
|
||||
### 1. Entry Read Time（进入读时）
|
||||
玩家在进入战斗前必须有时间感知威胁：
|
||||
- **禁止**：玩家无法在受击前看到敌人的位置（设计的伏击除外，但必须有预兆）
|
||||
- **标准**：敌人必须在玩家进入交战范围前可见
|
||||
- **伏击设计**：必须有 telegraph（预兆信号），如声音、光照变化、敌人标记
|
||||
|
||||
### Enemy Placement Rules
|
||||
- 禁止将敌人放在玩家进入视野前就能造成伤害的位置（设计好的伏击除外，但必须有预警信号）
|
||||
- 难度必须先从空间（位置和布局）出发，再考虑数值缩放
|
||||
- 所有敌人必须在玩家进入交战范围前可见
|
||||
### 2. Multiple Tactical Approaches（多种战术选项）
|
||||
每场战斗必须至少有 2 种在测试中被证明可行的战术：
|
||||
- **进攻选项**：正面突破、侧翼、包抄
|
||||
- **防守选项**：利用掩体、占据高点、等待冷却
|
||||
- **策略选项**：利用环境（可破坏物、陷阱触发物）
|
||||
- **禁止**：只有一种最优解的战斗设计
|
||||
|
||||
### Difficulty Hierarchy
|
||||
1. **Spatial first**（位置第一）：通过敌人位置和掩体布局创造难度
|
||||
2. **Stat scaling second**（数值第二）：在空间设计固定后，通过数值调整难度
|
||||
### 3. Fallback Position（撤退位置）
|
||||
玩家处于劣势时必须有脱离战场的空间选项：
|
||||
- **要求**：撤退位置必须在空间上明显（玩家能直觉感知）
|
||||
- **功能**：给予玩家重新评估局势、改变战术的机会
|
||||
- **平衡**：撤退位置不应该是绝对安全的（否则玩家永远不进攻）
|
||||
|
||||
## Tensions
|
||||
- **Readability vs. Surprise**：清晰战场 vs. 惊喜伏击，通过 telegraphing（预警）平衡
|
||||
- **Choice vs. Optimal**：多种战术选项 vs. 存在唯一最优解，通过 playtest 验证多样性
|
||||
## Difficulty Hierarchy
|
||||
|
||||
## Related Concepts
|
||||
- [[Flow And Readability]]：Encounter 是 Flow 路径上的节点
|
||||
- [[Blockout Discipline]]：Encounter 在灰盒阶段必须完成可玩性验证
|
||||
- [[Pacing Architecture]]：Encounter 的密度和强度决定整体节奏
|
||||
遭遇战难度应首先通过**空间设计**（位置、布局）而非数值缩放实现：
|
||||
|
||||
## Sources
|
||||
- [[Level Designer Agent Personality]]
|
||||
1. **Spatial Difficulty**（空间难度）：通过掩体数量、高低差、通道宽度实现
|
||||
2. **Tactical Difficulty**（战术难度）：通过敌人类型组合、AI 行为模式实现
|
||||
3. **Stat Difficulty**（数值难度）：作为最后手段，缩放敌人生命值/伤害
|
||||
|
||||
## Encounter List Template
|
||||
|
||||
```markdown
|
||||
## Encounter List
|
||||
|
||||
| ID | Type | Enemy Count | Tactical Options | Fallback Position |
|
||||
|-----|----------|-------------|------------------|-------------------|
|
||||
| E01 | Ambush | 4 | Flank / Suppress | Door archway |
|
||||
| E02 | Arena | 8 | 3 cover positions| Elevated platform |
|
||||
```
|
||||
|
||||
## Playtest Validation
|
||||
|
||||
- 每场遭遇战必须单独 Playtest 验证
|
||||
- 测量指标：time-to-death、成功战术分布、混乱时刻
|
||||
- 迭代标准：直到至少 2 种战术被测试者成功使用
|
||||
|
||||
## Connections
|
||||
|
||||
- [[Level Designer]] 是 Encounter Design 的核心执行者
|
||||
- [[Grey Box Blockout]] 阶段必须验证所有遭遇战
|
||||
- [[Spatial Psychology]] 影响撤退位置和有利地形的空间感知设计
|
||||
- [[Pacing Chart]] 中的 Combat 条目直接对应 Encounter Design 的节奏峰值
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user