---
title: Global Development Principles and Operational Rules
type: curated
permalink: main/global/curated/7aee455b-24cc-4008-bdaf-443721e6f939/contexts/global-development-principles-and-operational-rules
stable_id: 7b5a1fcd-adea-4418-ac8e-2f6275b5ada6
scope: global
project_id: null
workspace_type: global
usage_profile_id: 7aee455b-24cc-4008-bdaf-443721e6f939
preference_context: global
document_type: context_general
revision: 9
source_memory_ids:
- d8161df6-3159-46c9-9402-c5ab30d1436e
source_checkpoint_ids: []
source_file_ids: []
source_git_commit: null
source_git_commits: []
source_agent_sync_ids: []
model_connection: Sub2API
model_name: openai/gpt-oss-20b
source_count: 90
source_revisions:
  memory:bf88c265-4749-4c50-85bc-4bae25298cd5: '4'
  memory:5ed86f53-b53e-4534-8e51-d3a010069d5e: '2'
  memory:105b328f-4bda-4641-90a7-7282ef156316: '2'
  memory:3f91189b-11a1-45bb-8357-4f413dc1609d: '1'
source_dispositions:
  processed: 90
  unchanged: 0
  unsupported: 0
  skipped: 0
cited_source_ids:
- curated_baseline:7b5a1fcd-adea-4418-ac8e-2f6275b5ada6
- curated_baseline:d3a20d44-6001-4c88-8772-65dbfac75e6e
- cross_workspace_memory:6e63a053-fea4-4785-984c-b61fab08810a
- cross_workspace_memory:61e30ee3-0e26-4d64-b00e-f77bc3a3fd60
- cross_workspace_memory:df065dbf-85de-4f2b-bbb1-5d8b115de08c
- cross_workspace_memory:9f00df57-ec45-4d63-9da6-9b2fb16c2d6b
- cross_workspace_memory:0f19c98d-0d69-4702-af18-e75edae6370a
- cross_workspace_memory:1dfbc803-3390-4cc7-9a17-6bf86c9bb165
- cross_workspace_memory:5924806e-b234-49f7-b971-3c844fd07cf3
- curated_baseline:2b47472d-3ac2-4394-8646-c6bf1c0fc270
- memory:bf88c265-4749-4c50-85bc-4bae25298cd5
- memory:5ed86f53-b53e-4534-8e51-d3a010069d5e
- memory:105b328f-4bda-4641-90a7-7282ef156316
- memory:3f91189b-11a1-45bb-8357-4f413dc1609d
- cross_workspace_memory:b3fc5d7e-f1d7-4a63-860b-37f9f35cb136
- cross_workspace_memory:41e5bdb5-a67b-49bc-b8a6-ab20b4c66fca
- cross_workspace_memory:23bcc4c0-4992-41d6-b70e-210937a76a0f
- cross_workspace_memory:db92ba17-fcee-4f1d-9593-6b325105e482
- cross_workspace_memory:340af5e9-b3e5-423a-9971-b370992738ce
- cross_workspace_memory:b70c1a22-6834-4e59-936c-1945b04273b7
job_cited_source_ids:
- curated_baseline:7b5a1fcd-adea-4418-ac8e-2f6275b5ada6
conflicts: []
supersedes: []
preferences: []
source_cursor: 571
source_hash: b84354eb37ab531c5be3076d5c3f130399f235bc33c8cf9453cbfcecae042e49
prompt_version: 2026-08-12.3
schema_version: '3'
curation_job_id: ef77eb26-e282-4e81-88c8-7d622d14ccc7
created_at: '2026-08-08T07:55:54.432494+00:00'
updated_at: '2026-09-16T03:09:24.893133+00:00'
tags:
- general
---

# Current context_general

## 全局发展上下文（中文）

- **核心原则 (KISS & YAGNI)**：使用最简且正确的实现，复用项目已有的框架、服务、工具与约定，避免为假设需求引入依赖或抽象层。
- **开发平台**：统一使用 **Windows + WSL2 + Docker Desktop**（Linux 容器）。容器访问宿主服务通过 `host.docker.internal`，宿主服务必须监听 `0.0.0.0`。桥接网络访问宿主映射端口使用网关 `172.17.0.1`。
- **Docker Hub 代理配置**：Docker Desktop 代理必须设为 **Manual**，HTTP 与 HTTPS 均填写 `http://127.0.0.1:7897`，保存后重启 Docker 并验证 `docker pull` 正常后再进行构建。
- **常见技术坑与对策**：
  - *FastAPI async*：不要在 `async def` 内执行阻塞 I/O（pymysql、requests、文件 I/O 等）。改为普通 `def`，FastAPI 会自动转入线程池。
  - *PowerShell JSON*：先将 JSON 写入临时文件，再使用 `curl.exe --data-binary @file` 发送，以保持引号。
  - *大表 SQL*：对无索引文本列建索引；统一提升 DB `read/write_timeout=3600s`、客户端 `upload_timeout=1800s`、`run_timeout=7200s`。
  - *Docker exec 超时*：获取裸 socket 后调用 `socket.settimeout(None)`，取消默认 3 s 超时。
  - *Wheel 与 sdist 下载*：对 manylinux2014 wheel 采用 `--platform manylinux2014_x86_64`，sdist‑only 包通过 PyPI JSON API 下载源码 tar.gz。
  - *Docker Hub 代理*：在 Docker Desktop 中手动配置 `HTTP/HTTPS=http://127.0.0.1:7897` 并重启 Docker。
- **Git 规则**：见 curated 规则 `cross_workspace_memory:aa56cfd5-4cbf-4bbd-b589-03aaed17acb2`，默认仅 commit，除非用户明确请求推送。
- **项目记忆管理**：所有笔记保存在 `aidocs/project_context.md`，`.gitignore` 中不提交任何改动。