✨ feat(vscode): 代码阅读的注释挂到它讲的代码块上成「注释」一行，重写注释改用技能一句话加结构化结果

- 普通注释不再单独成卡片：同一层挂到后面最近的块（隔空行也算），后面没有挂到前面那块，整层没代码挂到父块；只有文件开头隔着空行的注释、模块 docstring、//!、@file 单独成「文件开头的说明」
- 各语言（Python、TypeScript、Rust、Shell、Dockerfile）建好树后统一调 attachComments；块的编辑范围连着挂上的注释，差异、跳转、钉住卡片都按它
- 宿主统一给每张卡片（语言卡片、翻译插件的属性表、库规则卡片、一行译文的语句卡片）插「注释」一行，排在名称、说明后面
- TypeScript 的 JSDoc 也能当常量、变量的说明；sqlx、React 不再单独处理前面的注释
- 「重写注释」每块都有：提示只发 /ecc:writing-code-comments 路径:起-止，模型只读、按 --json-schema 交 body，没交结构化正文就失败不写；扩展换掉块前面的注释或在块上面新写一段

vscode/src/codeReader/languages/python.ts

@@ -1,8 +1,8 @@
-import type { Access, BlockShape, CallArgument, CallFacts, ClassFacts, CodeBlock, EntryFacts, FunctionFacts, ImportFacts, ImportItem, IterationClause, IterationFacts, IterationResult, LanguageAdapter, Node, ParameterFacts, TextKind, TokenRole } from '../contract'
+import type { Access, BlockShape, CallArgument, CallFacts, ClassFacts, CodeBlock, CommentBlock, EntryFacts, FunctionFacts, ImportFacts, ImportItem, IterationClause, IterationFacts, IterationResult, LanguageAdapter, Node, ParameterFacts, TextKind, TokenRole } from '../contract'
 import type { CommentRules, ExceptionRules } from './shared'
 import * as path from 'node:path'
 import { pythonNameReader } from './pythonNames'
-import { children, compoundShape, leafBlock, leafShape, listBlocks, named, sameNode, syntaxChildren, withExceptions } from './shared'
+import { attachComments, children, compoundShape, leafBlock, leafShape, listBlocks, named, sameNode, syntaxChildren, withExceptions } from './shared'
 
 /** 常量、类字段只认直接写在模块 / 类主体里的赋值；这两处的声明也才有访问级别。 */
 type Scope = 'module' | 'class' | 'other'
@@ -12,8 +12,25 @@ const PARAMETER_SEPARATORS = new Set(['keyword_separator', 'positional_separator
 const PATTERNS = new Set(['pattern_list', 'tuple_pattern', 'list_pattern'])
 /** 字符串开头（string_start）：普通字符串的前缀只有 r / u 或没有；f、t、b 开头的不是。 */
 const STRING_PREFIX = /^[ru]?["']/i
-// 只有 # 行注释；函数、类的说明是主体开头的 docstring，不是写在前面的注释
-const COMMENTS: CommentRules = { lineStyle: () => '#', isDoc: () => false, documents: new Set() }
+/** PEP 263 写编码的注释：`# -*- coding: utf-8 -*-`、`# vim: set fileencoding=utf-8 :`。 */
+const CODING = /^#.*?coding[:=]\s*[-\w.]+/
+
+/** 文件头两行里写给解释器看的注释：第一行的 `#!`，头两行里写编码的。 */
+function isPragma(comment: Node): boolean {
+  const row = comment.startPosition.row
+  return (row === 0 && comment.text.startsWith('#!')) || (row <= 1 && CODING.test(comment.text))
+}
+
+// 只有 # 行注释；函数、类的说明是主体开头的 docstring，不是写在前面的注释。写给解释器的那两行不和后面的注释连成一块
+const COMMENTS: CommentRules = { lineStyle: comment => isPragma(comment) ? '#!' : '#', isDoc: () => false, documents: new Set() }
+
+/** 讲整个文件的注释：模块开头的 docstring（第一条语句，注释不算），写给解释器的那两行。 */
+function aboutModule(comment: CommentBlock): boolean {
+  const { node } = comment
+  if (node.type === 'comment')
+    return isPragma(node)
+  return node.parent?.type === 'module' && sameNode(named(node.parent).find(child => child.type !== 'comment'), node)
+}
 
 function statements(items: Node[], scope: Scope, afterRow: number): CodeBlock[] {
   const docs = attributeDocs(items, scope)
@@ -636,8 +653,9 @@ export function createPythonAdapter(wasmDir: string): LanguageAdapter {
     id: 'python',
     languageIds: ['python'],
     grammarPath: () => path.join(wasmDir, 'tree-sitter-python.wasm'),
-    toBlocks: root => withExceptions(statements(named(root), 'module', -1), PYTHON_EXCEPTIONS),
+    toBlocks: root => withExceptions(attachComments(statements(named(root), 'module', -1), aboutModule), PYTHON_EXCEPTIONS),
     tokenRole: pythonTokenRole,
+    lineComment: '#',
     iteration: pythonIteration,
     call: pythonCall,
     displayNames: pythonNameReader,