docs: compound any-and-except-exception-governance convention #12

ether · 2026-07-01T08:16:43+08:00

ether commented

2026-07-01 08:16:43 +08:00

Summary

Record the strategies established during PR #8-#11 (1214+ tech debt governance) into docs/solutions/conventions/ for future reference.

What's documented

Any 替代优先级: TypeAlias > object > TYPE_CHECKING Protocol > 字符串注解
except Exception 分类: WebSocket / DB / SQLAlchemy / HTTP / JSON / SQLite 各场景异常元组
框架边界保留: FastAPI/WebSocket/CLI 主循环保留 except Exception + CancelledError 守卫
设计意图保留: health_check/list_sources/解析器保留 except Exception
Pydantic v2 陷阱: 递归 TypeAlias 导致 RecursionError
SQLAlchemy 陷阱: DBAPIError 不继承 ConnectionError
测试陷阱: side_effect=Exception(...) 不在窄化元组中

ce-compound workflow notes

CONCEPTS.md: 无需更新（新文档讨论的 Any/except 是通用编程词汇，非项目特有域名词）
AGENTS.md discoverability: 已满足（第 205 行已提及 docs/solutions/ 及 YAML frontmatter 可搜索性）
Track: Knowledge track (problem_type: convention)

## Summary Record the strategies established during PR #8-#11 (1214+ tech debt governance) into `docs/solutions/conventions/` for future reference. ## What's documented - **Any 替代优先级**: TypeAlias > `object` > TYPE_CHECKING Protocol > 字符串注解 - **except Exception 分类**: WebSocket / DB / SQLAlchemy / HTTP / JSON / SQLite 各场景异常元组 - **框架边界保留**: FastAPI/WebSocket/CLI 主循环保留 `except Exception` + CancelledError 守卫 - **设计意图保留**: `health_check`/`list_sources`/解析器保留 `except Exception` - **Pydantic v2 陷阱**: 递归 TypeAlias 导致 RecursionError - **SQLAlchemy 陷阱**: DBAPIError 不继承 ConnectionError - **测试陷阱**: `side_effect=Exception(...)` 不在窄化元组中 ## ce-compound workflow notes - **CONCEPTS.md**: 无需更新（新文档讨论的 Any/except 是通用编程词汇，非项目特有域名词） - **AGENTS.md discoverability**: 已满足（第 205 行已提及 `docs/solutions/` 及 YAML frontmatter 可搜索性） - **Track**: Knowledge track (problem_type: convention)

ether added 1 commit 2026-07-01 08:16:44 +08:00

Test / backend-test (pull_request) Has been cancelled Details

Test / frontend-unit (pull_request) Has been cancelled Details

Test / api-e2e (pull_request) Has been cancelled Details

Test / frontend-e2e (pull_request) Has been cancelled Details

975b7c4e57 docs: compound any-and-except-exception-governance convention

Record the strategies established during PR #8-#11 (1214+ tech debt
governance) for Any replacement priority, except Exception classification,
framework boundary preservation, and intentional-design retention.

ether merged commit 521f573d4a into main

2026-07-01 08:16:55 +08:00

ether referenced this issue from a commit

2026-07-01 08:16:57 +08:00

docs: compound any-and-except-exception-governance convention (#12)

Sign in to join this conversation.

No reviewers

No Label

No Milestone

No project

No Assignees

1 Participants

Notifications

Due Date

The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: fischer/fischer-agentkit#12