Skip to content

Commit 4526d85

Browse files
thirdgerbthirdgerb
authored
Merge pull request #13 from IthacaDream/chore/format-and-lint
chore: Add linting and formatting, improve repo hygiene and developer…
2 parents 4a23187 + 4166eff commit 4526d85

File tree

188 files changed

+4075
-3368
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

188 files changed

+4075
-3368
lines changed

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,4 +174,5 @@ cython_debug/
174174

175175
.vscode/
176176

177-
.setup_env
177+
.setup_env
178+
.uv_cache

‎.pre-commit-config.yaml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
repos:
2+
3+
- repo: local
4+
hooks:
5+
- id: ruff-format
6+
name: ruff-format
7+
description: "Run 'ruff format' for extremely fast Python formatting"
8+
entry: uv run --dev ruff format
9+
pass_filenames: false
10+
always_run: true
11+
language: python
12+
types_or: [python, pyi, jupyter]
13+
args: []
14+
require_serial: true
15+
additional_dependencies: []
16+
17+
- id: ruff
18+
name: ruff
19+
description: "Run 'ruff' for extremely fast Python linting"
20+
entry: uv run --dev ruff check
21+
pass_filenames: false
22+
always_run: true
23+
language: python
24+
types_or: [python, pyi, jupyter]
25+
args: []
26+
require_serial: true
27+
additional_dependencies: []
28+
29+
- id: mdformat
30+
name: mdformat
31+
description: "Run 'mdformat' for Markdown formatting"
32+
entry: uv run --dev mdformat
33+
language: system
34+
types: [markdown]

‎.ruff.toml‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
exclude = ["docs/**"]
2+
line-length = 120
3+
4+
[format]
5+
quote-style = "double"
6+
7+
[lint]
8+
preview = true
9+
select = [
10+
"B", # flake8-bugbear rules
11+
"C4", # flake8-comprehensions
12+
"E", # pycodestyle E rules
13+
"F", # pyflakes rules
14+
"FURB", # refurb rules
15+
"I", # isort rules
16+
"N", # pep8-naming
17+
"PT", # flake8-pytest-style rules
18+
"PLC0208", # iteration-over-set
19+
"PLC0414", # useless-import-alias
20+
"PLE0604", # invalid-all-object
21+
"PLE0605", # invalid-all-format
22+
"PLR0402", # manual-from-import
23+
"PLR1711", # useless-return
24+
"PLR1714", # repeated-equality-comparison
25+
"RUF013", # implicit-optional
26+
"RUF019", # unnecessary-key-check
27+
"RUF100", # unused-noqa
28+
"RUF101", # redirected-noqa
29+
"RUF200", # invalid-pyproject-toml
30+
"RUF022", # unsorted-dunder-all
31+
"S506", # unsafe-yaml-load
32+
"SIM", # flake8-simplify rules
33+
# "T201", # print-found
34+
"TRY400", # error-instead-of-exception
35+
"TRY401", # verbose-log-message
36+
"UP", # pyupgrade rules
37+
"W191", # tab-indentation
38+
"W605", # invalid-escape-sequence
39+
"G001", # don't use str format to logging messages
40+
"G003", # don't use + in logging messages
41+
"G004", # don't use f-strings to format logging messages
42+
"UP042", # use StrEnum,
43+
"S110", # disallow the try-except-pass pattern.
44+
45+
# security related linting rules
46+
# RCE proctection (sort of)
47+
"S102", # exec-builtin, disallow use of `exec`
48+
"S307", # suspicious-eval-usage, disallow use of `eval` and `ast.literal_eval`
49+
"S301", # suspicious-pickle-usage, disallow use of `pickle` and its wrappers.
50+
"S302", # suspicious-marshal-usage, disallow use of `marshal` module
51+
"S311", # suspicious-non-cryptographic-random-usage,
52+
53+
]
54+
55+
ignore = [
56+
"E402", # module-import-not-at-top-of-file
57+
"E711", # none-comparison
58+
"E712", # true-false-comparison
59+
"E721", # type-comparison
60+
"E722", # bare-except
61+
"F821", # undefined-name
62+
"F841", # unused-variable
63+
"FURB113", # repeated-append
64+
"FURB152", # math-constant
65+
"UP007", # non-pep604-annotation
66+
"UP032", # f-string
67+
"UP045", # non-pep604-annotation-optional
68+
"B005", # strip-with-multi-characters
69+
"B006", # mutable-argument-default
70+
"B007", # unused-loop-control-variable
71+
"B026", # star-arg-unpacking-after-keyword-arg
72+
"B901", # allow return in yield
73+
"B903", # class-as-data-structure
74+
"B904", # raise-without-from-inside-except
75+
"B905", # zip-without-explicit-strict
76+
"N806", # non-lowercase-variable-in-function
77+
"N815", # mixed-case-variable-in-class-scope
78+
"PT011", # pytest-raises-too-broad
79+
"SIM102", # collapsible-if
80+
"SIM103", # needless-bool
81+
"SIM105", # suppressible-exception
82+
"SIM107", # return-in-try-except-finally
83+
"SIM108", # if-else-block-instead-of-if-exp
84+
"SIM113", # enumerate-for-loop
85+
"SIM117", # multiple-with-statements
86+
"SIM210", # if-expr-with-true-false
87+
]
88+
89+
[lint.per-file-ignores]
90+
"__init__.py" = [
91+
"F403", # allow re-export via star imports in packages
92+
"F401", # unused-import
93+
"F811", # redefined-while-unused
94+
]
95+
"configs/*" = [
96+
"N802", # invalid-function-name
97+
]
98+
99+
"tests/*" = [
100+
"F811", # redefined-while-unused
101+
"T201", # allow print in tests,
102+
"S110", # allow ignoring exceptions in tests code (currently)
103+
"S311", # random is fine in tests
104+
105+
]
106+
107+
"src/ghoshell_moss/core/ctml/token_parser.py" = [
108+
"N802", # SAX handler method names are fixed by the protocol
109+
"N818", # exception names are part of public API
110+
]
111+
112+
"src/ghoshell_moss/core/duplex/connection.py" = [
113+
"N818", # exception names are part of public API
114+
]
115+
116+
[lint.pyflakes]
117+
allowed-unused-imports = [
118+
"_pytest.monkeypatch",
119+
"tests.integration_tests",
120+
"tests.unit_tests",
121+
]

‎CONTRIBUTING.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Contributing
2+
3+
Thank you for your interest in contributing to `MOSShell`! This document provides guidelines and instructions for contributing.
4+
5+
## Before You Start
6+
7+
We welcome contributions! These guidelines exist to save everyone time. Following them means your work is more likely to be accepted.
8+
9+
**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.
10+
11+
## Development Setup
12+
13+
1. Make sure you have `Python 3.12+` installed.
14+
1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/).
15+
1. Fork the repository and clone your fork.
16+
1. Install development dependencies: `make prepare`.
17+
1. Create a new branch and make your changes.
18+
1. Run formatting, linting, and tests before submitting a PR:
19+
20+
```bash
21+
make format
22+
make lint
23+
make test
24+
```
25+
26+
### Checklist
27+
28+
- Update documentation as needed.
29+
- Add tests for new functionality.
30+
- Ensure CI passes.
31+
- Address review feedback.

‎Makefile‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
.DEFAULT_GOAL := prepare
2+
3+
export PATH := $(HOME)/.local/bin:$(PATH)
4+
5+
.PHONY: help
6+
help: ## Show available make targets.
7+
@echo "Available make targets:"
8+
@awk 'BEGIN { FS = ":.*## " } /^[A-Za-z0-9_.-]+:.*## / { printf " %-20s %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
9+
10+
.PHONY: install-uv
11+
install-uv: ## Install uv if missing
12+
@echo "==> Checking for uv"
13+
@if command -v uv >/dev/null 2>&1; then \
14+
echo "uv already installed at $$(command -v uv)"; \
15+
else \
16+
echo "uv not found. Installing via curl script..."; \
17+
curl -LsSf https://astral.sh/uv/install.sh | sh; \
18+
fi
19+
20+
.PHONY: install-python
21+
install-python: ## Install Python via uv if missing
22+
@echo "==> Ensuring Python 3.12 is available (via uv)"
23+
@if uv python find 3.12 >/dev/null 2>&1; then \
24+
echo "Python 3.12 already available"; \
25+
else \
26+
echo "Python 3.12 not found. Installing..."; \
27+
uv python install 3.12; \
28+
fi
29+
30+
.PHONY: uv-venv
31+
uv-venv: ## Create project virtualenv with uv if missing
32+
@echo "==> Checking for .venv"
33+
@if [ -d .venv ]; then \
34+
echo ".venv already exists"; \
35+
else \
36+
echo "Creating .venv with uv"; \
37+
uv venv; \
38+
fi
39+
40+
.PHONY: install-uv-pyenv
41+
install-uv-pyenv: install-uv install-python uv-venv ## Install uv, Python 3.12, and venv
42+
43+
.PHONY: install-prek
44+
install-prek: ## Install prek and repo git hooks.
45+
@echo "==> Installing prek"
46+
@uv tool install prek
47+
@echo "==> Installing git hooks with prek"
48+
@uv tool run prek install
49+
50+
.PHONY: prepare
51+
prepare: install-uv install-python uv-venv install-prek ## Setup uv, Python 3.12, venv, and prek hooks.
52+
@echo "==> Syncing dependencies for all workspace packages"
53+
@uv sync --dev --all-extras
54+
55+
MDFORMAT := $(shell if [ -x .venv/bin/mdformat ]; then echo .venv/bin/mdformat; else echo "uv run --dev mdformat"; fi)
56+
57+
.PHONY: format
58+
format: ## Run format
59+
@echo "==> Formatting"
60+
@uv run --dev ruff format
61+
@git ls-files -z '*.md' | xargs -0 $(MDFORMAT)
62+
63+
.PHONY: lint
64+
lint: ## Run lint
65+
@echo "==> Linting"
66+
@uv run --dev ruff check
67+
68+
.PHONY: type-check
69+
type-check:
70+
@echo "==> checking types"
71+
@uv run --dev ty check
72+
# @uv run --dev basedpyright
73+
74+
.PHONY: test
75+
test: ## Run pytest
76+
@echo "==> Testing"
77+
@uv run --dev pytest

‎README.md‎

Lines changed: 25 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,11 @@
33
项目名为 `MOS-Shell` (Model-oriented Operating System Shell), 包含两个几个核心目标:
44

55
1. `MOS`: 为 AI 大模型提供一个 "面向模型的操作系统", 可以将 跨设备/跨进程 的功能模块, 以 "树" 的形式提供给模型操作.
6-
2. `Shell Runtime`: 为 AI Agent 提供一个持续运转的运行时 (Runtime), 联通所有功能模块 (称之为 Channel, 对标 python 的
6+
1. `Shell Runtime`: 为 AI Agent 提供一个持续运转的运行时 (Runtime), 联通所有功能模块 (称之为 Channel, 对标 python 的
77
module).
8-
3. `Code As Prompt`: 让 AI 大模型用 python 函数 的形式理解所有它可调用的功能, 而不是 json schema. 实现 "
8+
1. `Code As Prompt`: 让 AI 大模型用 python 函数 的形式理解所有它可调用的功能, 而不是 json schema. 实现 "
99
面向模型的编程语言".
10-
4. `Streaming Interpret`: 支持 AI 大模型流式输出对话和命令 (Command) 调用, 并且 Shell 会流式地编译执行这些调用,
10+
1. `Streaming Interpret`: 支持 AI 大模型流式输出对话和命令 (Command) 调用, 并且 Shell 会流式地编译执行这些调用,
1111
并行多轨控制自己的躯体和软件.
1212

1313
目标是 AI 大模型作为大脑, 不仅可以思考, 还可以 实时/并行/有序 地操作包括 计算机/具身躯体 来进行交互.
@@ -16,38 +16,43 @@ MOS-Shell 是 Ghost In Shells (中文名: 灵枢) 项目创建的新交互范式
1616
Realtime-Actions 思想).
1717
第一代 MOSS 架构 (全代码驱动 + FunctionToken) 详见 [GhostOS](https://github.com/ghostInShells/ghostos)
1818

19-
# Alpha 版本声明
19+
## Alpha 版本声明
2020

2121
当前版本为内测版 (Alpha), 这意味着:
2222

2323
1. 项目仍然在第一阶段开发中, 会激进地迭代.
24-
2. 主要是验证核心链路和设计思想, 许多计划中的关键功能还未实现.
25-
3. 暂时没有人力去完善文档
26-
4. 不适合在生产环境使用.
24+
1. 主要是验证核心链路和设计思想, 许多计划中的关键功能还未实现.
25+
1. 暂时没有人力去完善文档
26+
1. 不适合在生产环境使用.
2727

2828
如果想要试用项目, 请直接联系 灵枢开发组 配合.
2929

30-
# Examples
30+
## Examples
3131

3232
本处放置如何使用 Alpha 版本的说明. 预计 2026-02-08 完成.
3333

34-
# Beta Roadmap
34+
## Beta Roadmap
3535

3636
Alpha 版本是内测版. 预计在 Beta 版本完成:
3737

3838
- [ ] 中英双语说明文档
3939
- [ ] 流式控制基线
40-
- [ ] CTML 控制原语: clear / stop_all / wait / concurrent / observe. 目前原语未完成, 多轨并行和阻塞存在问题.
41-
- [ ] Speech 模块 Channel 化.
42-
- [ ] 完善 CommandResult, 用于支持正规的 Agent 交互范式.
43-
- [ ] 完善 states/topics 等核心技术模块.
44-
- [ ] 完善 Interpreter 与 AI Agent 的交互范式基线.
40+
- [ ] CTML 控制原语: clear / stop_all / wait / concurrent / observe. 目前原语未完成, 多轨并行和阻塞存在问题.
41+
- [ ] Speech 模块 Channel 化.
42+
- [ ] 完善 CommandResult, 用于支持正规的 Agent 交互范式.
43+
- [ ] 完善 states/topics 等核心技术模块.
44+
- [ ] 完善 Interpreter 与 AI Agent 的交互范式基线.
4545
- [ ] 完善 Channel 体系
46-
- [ ] 定义 Channel App 范式, 创建本地的 Channel Applications Store
47-
- [ ] 完善 Channel 运行时生命周期治理
48-
- [ ] 完成对 Claude MCP 和 Skill 的兼容
46+
- [ ] 定义 Channel App 范式, 创建本地的 Channel Applications Store
47+
- [ ] 完善 Channel 运行时生命周期治理
48+
- [ ] 完成对 Claude MCP 和 Skill 的兼容
4949
- [ ] 完善 MOSS 项目的自解释 AI
50-
- [ ] 实现第一个 Ghost 原型, 代号 Alice
51-
- [ ] 实现架构级的 Channels, 用于支撑基于 MOSS 运转的 Ghost 体系.
52-
- [ ] 实现一部分开箱即用的 Channels, 用来提供 AIOS 的运行基线.
50+
- [ ] 实现第一个 Ghost 原型, 代号 Alice
51+
- [ ] 实现架构级的 Channels, 用于支撑基于 MOSS 运转的 Ghost 体系.
52+
- [ ] 实现一部分开箱即用的 Channels, 用来提供 AIOS 的运行基线.
5353

54+
## Contributing
55+
56+
- Thank you for being interested in contributing to `MOSShell`!
57+
- We welcome all kinds of contributions. Whether you're fixing bugs, adding features, or improving documentation, we appreciate your help.
58+
- For those who'd like to contribute code, see our [Contribution Guide](https://github.com/GhostInShells/MOSShell/blob/main/CONTRIBUTING.md).

‎RELEASES.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
# v0.1.0-alpha
22

3-
ghoshell-moss 第一个正式版本.
3+
ghoshell-moss 第一个正式版本.

‎ai_partners/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
# partners
22

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

0 commit comments

Comments
 (0)