chore: Add linting and formatting, improve repo hygiene and developer…

.gitignore

@@ -174,4 +174,5 @@ cython_debug/
 
 .vscode/
 
-.setup_env
+.setup_env
+.uv_cache

.pre-commit-config.yaml

@@ -0,0 +1,34 @@
+repos:
+
+- repo: local
+  hooks:
+    - id: ruff-format
+      name: ruff-format
+      description: "Run 'ruff format' for extremely fast Python formatting"
+      entry: uv run --dev ruff format
+      pass_filenames: false
+      always_run: true
+      language: python
+      types_or: [python, pyi, jupyter]
+      args: []
+      require_serial: true
+      additional_dependencies: []
+
+    - id: ruff
+      name: ruff
+      description: "Run 'ruff' for extremely fast Python linting"
+      entry: uv run --dev ruff check
+      pass_filenames: false
+      always_run: true
+      language: python
+      types_or: [python, pyi, jupyter]
+      args: []
+      require_serial: true
+      additional_dependencies: []
+
+    - id: mdformat
+      name: mdformat
+      description: "Run 'mdformat' for Markdown formatting"
+      entry: uv run --dev mdformat
+      language: system
+      types: [markdown]

.ruff.toml

@@ -0,0 +1,121 @@
+exclude = ["docs/**"]
+line-length = 120
+
+[format]
+quote-style = "double"
+
+[lint]
+preview = true
+select = [
+    "B",       # flake8-bugbear rules
+    "C4",      # flake8-comprehensions
+    "E",       # pycodestyle E rules
+    "F",       # pyflakes rules
+    "FURB",    # refurb rules
+    "I",       # isort rules
+    "N",       # pep8-naming
+    "PT",      # flake8-pytest-style rules
+    "PLC0208", # iteration-over-set
+    "PLC0414", # useless-import-alias
+    "PLE0604", # invalid-all-object
+    "PLE0605", # invalid-all-format
+    "PLR0402", # manual-from-import
+    "PLR1711", # useless-return
+    "PLR1714", # repeated-equality-comparison
+    "RUF013",  # implicit-optional
+    "RUF019",  # unnecessary-key-check
+    "RUF100",  # unused-noqa
+    "RUF101",  # redirected-noqa
+    "RUF200",  # invalid-pyproject-toml
+    "RUF022",  # unsorted-dunder-all
+    "S506",    # unsafe-yaml-load
+    "SIM",     # flake8-simplify rules
+    # "T201",    # print-found
+    "TRY400", # error-instead-of-exception
+    "TRY401", # verbose-log-message
+    "UP",     # pyupgrade rules
+    "W191",   # tab-indentation
+    "W605",   # invalid-escape-sequence
+    "G001",   # don't use str format to logging messages
+    "G003",   # don't use + in logging messages
+    "G004",   # don't use f-strings to format logging messages
+    "UP042",  # use StrEnum,
+    "S110",   # disallow the try-except-pass pattern.
+
+    # security related linting rules
+    # RCE proctection (sort of)
+    "S102", # exec-builtin, disallow use of `exec`
+    "S307", # suspicious-eval-usage, disallow use of `eval` and `ast.literal_eval`
+    "S301", # suspicious-pickle-usage, disallow use of `pickle` and its wrappers.
+    "S302", # suspicious-marshal-usage, disallow use of `marshal` module
+    "S311", # suspicious-non-cryptographic-random-usage,
+
+]
+
+ignore = [
+    "E402",    # module-import-not-at-top-of-file
+    "E711",    # none-comparison
+    "E712",    # true-false-comparison
+    "E721",    # type-comparison
+    "E722",    # bare-except
+    "F821",    # undefined-name
+    "F841",    # unused-variable
+    "FURB113", # repeated-append
+    "FURB152", # math-constant
+    "UP007",   # non-pep604-annotation
+    "UP032",   # f-string
+    "UP045",   # non-pep604-annotation-optional
+    "B005",    # strip-with-multi-characters
+    "B006",    # mutable-argument-default
+    "B007",    # unused-loop-control-variable
+    "B026",    # star-arg-unpacking-after-keyword-arg
+    "B901",    # allow return in yield
+    "B903",    # class-as-data-structure
+    "B904",    # raise-without-from-inside-except
+    "B905",    # zip-without-explicit-strict
+    "N806",    # non-lowercase-variable-in-function
+    "N815",    # mixed-case-variable-in-class-scope
+    "PT011",   # pytest-raises-too-broad
+    "SIM102",  # collapsible-if
+    "SIM103",  # needless-bool
+    "SIM105",  # suppressible-exception
+    "SIM107",  # return-in-try-except-finally
+    "SIM108",  # if-else-block-instead-of-if-exp
+    "SIM113",  # enumerate-for-loop
+    "SIM117",  # multiple-with-statements
+    "SIM210",  # if-expr-with-true-false
+]
+
+[lint.per-file-ignores]
+"__init__.py" = [
+    "F403", # allow re-export via star imports in packages
+    "F401", # unused-import
+    "F811", # redefined-while-unused
+]
+"configs/*" = [
+    "N802", # invalid-function-name
+]
+
+"tests/*" = [
+    "F811", # redefined-while-unused
+    "T201", # allow print in tests,
+    "S110", # allow ignoring exceptions in tests code (currently)
+    "S311", # random is fine in tests
+
+]
+
+"src/ghoshell_moss/core/ctml/token_parser.py" = [
+    "N802", # SAX handler method names are fixed by the protocol
+    "N818", # exception names are part of public API
+]
+
+"src/ghoshell_moss/core/duplex/connection.py" = [
+    "N818", # exception names are part of public API
+]
+
+[lint.pyflakes]
+allowed-unused-imports = [
+    "_pytest.monkeypatch",
+    "tests.integration_tests",
+    "tests.unit_tests",
+]

CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+Thank you for your interest in contributing to `MOSShell`! This document provides guidelines and instructions for contributing.
+
+## Before You Start
+
+We welcome contributions! These guidelines exist to save everyone time. Following them means your work is more likely to be accepted.
+
+**All pull requests require a corresponding issue.** Unless your change is trivial (typo, docs tweak, broken link), create an issue first. Every merged feature becomes ongoing maintenance, so we need to agree that it's worth doing before reviewing code. PRs without a linked issue will be closed.
+
+## Development Setup
+
+1. Make sure you have `Python 3.12+` installed.
+1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/).
+1. Fork the repository and clone your fork.
+1. Install development dependencies: `make prepare`.
+1. Create a new branch and make your changes.
+1. Run formatting, linting, and tests before submitting a PR:
+
+```bash
+make format
+make lint
+make test
+```
+
+### Checklist
+
+- Update documentation as needed.
+- Add tests for new functionality.
+- Ensure CI passes.
+- Address review feedback.

Makefile

@@ -0,0 +1,77 @@
+.DEFAULT_GOAL := prepare
+
+export PATH := $(HOME)/.local/bin:$(PATH)
+
+.PHONY: help
+help: ## Show available make targets.
+	@echo "Available make targets:"
+	@awk 'BEGIN { FS = ":.*## " } /^[A-Za-z0-9_.-]+:.*## / { printf "  %-20s %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
+
+.PHONY: install-uv
+install-uv: ## Install uv if missing
+	@echo "==> Checking for uv"
+	@if command -v uv >/dev/null 2>&1; then \
+		echo "uv already installed at $$(command -v uv)"; \
+	else \
+		echo "uv not found. Installing via curl script..."; \
+		curl -LsSf https://astral.sh/uv/install.sh | sh; \
+	fi
+
+.PHONY: install-python
+install-python: ## Install Python via uv if missing
+	@echo "==> Ensuring Python 3.12 is available (via uv)"
+	@if uv python find 3.12 >/dev/null 2>&1; then \
+		echo "Python 3.12 already available"; \
+	else \
+		echo "Python 3.12 not found. Installing..."; \
+		uv python install 3.12; \
+	fi
+
+.PHONY: uv-venv
+uv-venv: ## Create project virtualenv with uv if missing
+	@echo "==> Checking for .venv"
+	@if [ -d .venv ]; then \
+		echo ".venv already exists"; \
+	else \
+		echo "Creating .venv with uv"; \
+		uv venv; \
+	fi
+
+.PHONY: install-uv-pyenv
+install-uv-pyenv: install-uv install-python uv-venv ## Install uv, Python 3.12, and venv
+
+.PHONY: install-prek
+install-prek: ## Install prek and repo git hooks.
+	@echo "==> Installing prek"
+	@uv tool install prek
+	@echo "==> Installing git hooks with prek"
+	@uv tool run prek install
+
+.PHONY: prepare
+prepare: install-uv install-python uv-venv install-prek ## Setup uv, Python 3.12, venv, and prek hooks.
+	@echo "==> Syncing dependencies for all workspace packages"
+	@uv sync --dev --all-extras
+
+MDFORMAT := $(shell if [ -x .venv/bin/mdformat ]; then echo .venv/bin/mdformat; else echo "uv run --dev mdformat"; fi)
+
+.PHONY: format
+format: ## Run format
+	@echo "==> Formatting"
+	@uv run --dev ruff format
+	@git ls-files -z '*.md' | xargs -0 $(MDFORMAT)
+
+.PHONY: lint
+lint: ## Run lint
+	@echo "==> Linting"
+	@uv run --dev ruff check
+
+.PHONY: type-check
+type-check:
+	@echo "==> checking types"
+	@uv run --dev ty check
+	# @uv run --dev basedpyright
+
+.PHONY: test
+test: ## Run pytest
+	@echo "==> Testing"
+	@uv run --dev pytest

README.md

@@ -3,11 +3,11 @@
 项目名为 `MOS-Shell` (Model-oriented Operating System Shell), 包含两个几个核心目标:
 
 1. `MOS`: 为 AI 大模型提供一个 "面向模型的操作系统", 可以将 跨设备/跨进程 的功能模块, 以 "树" 的形式提供给模型操作.
-2. `Shell Runtime`: 为 AI Agent 提供一个持续运转的运行时 (Runtime), 联通所有功能模块 (称之为 Channel, 对标 python 的
+1. `Shell Runtime`: 为 AI Agent 提供一个持续运转的运行时 (Runtime), 联通所有功能模块 (称之为 Channel, 对标 python 的
    module).
-3. `Code As Prompt`: 让 AI 大模型用 python 函数 的形式理解所有它可调用的功能, 而不是 json schema. 实现 "
+1. `Code As Prompt`: 让 AI 大模型用 python 函数 的形式理解所有它可调用的功能, 而不是 json schema. 实现 "
    面向模型的编程语言".
-4. `Streaming Interpret`: 支持 AI 大模型流式输出对话和命令 (Command) 调用, 并且 Shell 会流式地编译执行这些调用,
+1. `Streaming Interpret`: 支持 AI 大模型流式输出对话和命令 (Command) 调用, 并且 Shell 会流式地编译执行这些调用,
    并行多轨控制自己的躯体和软件.
 
 目标是 AI 大模型作为大脑, 不仅可以思考, 还可以 实时/并行/有序 地操作包括 计算机/具身躯体 来进行交互.
@@ -16,38 +16,43 @@ MOS-Shell 是 Ghost In Shells (中文名: 灵枢) 项目创建的新交互范式
 Realtime-Actions 思想).
 第一代 MOSS 架构 (全代码驱动 + FunctionToken) 详见 [GhostOS](https://github.com/ghostInShells/ghostos)
 
-# Alpha 版本声明
+## Alpha 版本声明
 
 当前版本为内测版 (Alpha), 这意味着:
 
 1. 项目仍然在第一阶段开发中, 会激进地迭代.
-2. 主要是验证核心链路和设计思想, 许多计划中的关键功能还未实现.
-3. 暂时没有人力去完善文档
-4. 不适合在生产环境使用.
+1. 主要是验证核心链路和设计思想, 许多计划中的关键功能还未实现.
+1. 暂时没有人力去完善文档
+1. 不适合在生产环境使用.
 
 如果想要试用项目, 请直接联系 灵枢开发组 配合.
 
-# Examples
+## Examples
 
 本处放置如何使用 Alpha 版本的说明. 预计 2026-02-08 完成.
 
-# Beta Roadmap
+## Beta Roadmap
 
 Alpha 版本是内测版. 预计在 Beta 版本完成:
 
 - [ ] 中英双语说明文档
 - [ ] 流式控制基线
-    - [ ] CTML 控制原语: clear / stop_all / wait / concurrent / observe. 目前原语未完成, 多轨并行和阻塞存在问题.
-    - [ ] Speech 模块 Channel 化.
-    - [ ] 完善 CommandResult, 用于支持正规的 Agent 交互范式.
-    - [ ] 完善 states/topics 等核心技术模块.
-    - [ ] 完善 Interpreter 与 AI Agent 的交互范式基线.
+  - [ ] CTML 控制原语: clear / stop_all / wait / concurrent / observe. 目前原语未完成, 多轨并行和阻塞存在问题.
+  - [ ] Speech 模块 Channel 化.
+  - [ ] 完善 CommandResult, 用于支持正规的 Agent 交互范式.
+  - [ ] 完善 states/topics 等核心技术模块.
+  - [ ] 完善 Interpreter 与 AI Agent 的交互范式基线.
 - [ ] 完善 Channel 体系
-    - [ ] 定义 Channel App 范式, 创建本地的 Channel Applications Store
-    - [ ] 完善 Channel 运行时生命周期治理
-    - [ ] 完成对 Claude MCP 和 Skill 的兼容
+  - [ ] 定义 Channel App 范式, 创建本地的 Channel Applications Store
+  - [ ] 完善 Channel 运行时生命周期治理
+  - [ ] 完成对 Claude MCP 和 Skill 的兼容
 - [ ] 完善 MOSS 项目的自解释 AI
-    - [ ] 实现第一个 Ghost 原型, 代号 Alice
-    - [ ] 实现架构级的 Channels, 用于支撑基于 MOSS 运转的 Ghost 体系.
-    - [ ] 实现一部分开箱即用的 Channels, 用来提供 AIOS 的运行基线. 
+  - [ ] 实现第一个 Ghost 原型, 代号 Alice
+  - [ ] 实现架构级的 Channels, 用于支撑基于 MOSS 运转的 Ghost 体系.
+  - [ ] 实现一部分开箱即用的 Channels, 用来提供 AIOS 的运行基线.
 
+## Contributing
+
+- Thank you for being interested in contributing to `MOSShell`!
+- We welcome all kinds of contributions. Whether you're fixing bugs, adding features, or improving documentation, we appreciate your help.
+- For those who'd like to contribute code, see our [Contribution Guide](https://github.com/GhostInShells/MOSShell/blob/main/CONTRIBUTING.md).

RELEASES.md

@@ -1,3 +1,3 @@
 # v0.1.0-alpha
 
-ghoshell-moss 第一个正式版本. 
+ghoshell-moss 第一个正式版本.

ai_partners/README.md

@@ -1,4 +1,4 @@
 # partners
 
 本目录用来暂时存放 MOSS 项目 AI 开发伙伴的 prompt 和一些对话记录.
-等长期记忆模块完成后, 迁移到指定目录. 
+等长期记忆模块完成后, 迁移到指定目录.